Skip to content
Oblique Docs

UpdateListingRole

PATCH/api/v1/listings/{listing}/roles/{role}

Update the description or display name of a role that users can request access to.

Example request

curl -X PATCH \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "string", "priority": "string" }' \
  "https://us.oblique.security/api/v1/listings/{listing}/roles/{role}?updateMask=displayName,priority"

Set OBLIQUE_API_KEY to your API key.

Path parameters

  • listingRole.namestringrequired

    Assigned by Oblique. Name of the role of the format listings/{listing}/roles/{role}.

Query parameters

  • updateMaskstring (field-mask)

    The list of fields to update.

    For non-admins this is required, and can’t include “resources”.

  • allowMissingboolean

    If set to true, and the listing role is not found, a new listing role will be created with the given name. If created in this way, update_mask is ignored.

Request body

  • createTimestring (date-time)read-only

    Create and update timestamps.

  • updateTimestring (date-time)read-only
  • deleteTimestring (date-time)read-only

    If present, the listing role has been deleted and won’t be returned in List operations.

  • displayNamestringrequired

    A short display name of the role. For example “Viewer”, “Editor”, or “Admin”.

  • descriptionstring

    A longer description of the role explaining to the end user when they would request this role over another role.

  • resourcesstring[]

    The set of resources that represent the role.

    When requesting a role, the target user, team, or group will be granted entitlements for all resources in this list, regardless of existing entitlements. For example, if a user has an entitlement for one resource out of two, they will be granted access to the second.

    Updating the list of resources does NOT change any entitlements that were granted through previous requests for this role. Removing a resource does NOT revoke access. Adding a resource does NOT grant access.

  • prioritystring (int64)required

    Priority indicates the order roles are displayed to the user. Generally roles with less access should be first (“Viewer”, “Editor”, “Admin”). Roles with lower priority values are displayed first. For example:

    • “Viewer” (priority = 0)
    • “Editor” (priority = 1)
    • “Admin” (priority = 2)
  • managementManagement

    How this role is managed. Inherited from the parent listing: roles of Terraform-managed listings are themselves Terraform managed and can only be created, updated, or deleted through the Terraform provider; manage the parent listing to change this. Omitted from responses when the parent listing is manually managed (the default).

    • managerstring
      Allowed values: TERRAFORM

      How the resource is managed. Set automatically by the server based on the caller: Terraform clients produce TERRAFORM; for all other clients the management field is left unset on the response.

    • repoUristring

      URI of the VCS repository that holds the Terraform configuration for this resource. Populated by the Oblique Terraform provider.

    • repoDirstring

      Optionally, the subdirectory within repo_uri that holds the Terraform configuration for this resource. Populated by the Oblique Terraform provider.

Response

200ListingRole

ListingRole is the set of roles that can be requested for a listing.

  • namestring

    Assigned by Oblique. Name of the role of the format listings/{listing}/roles/{role}.

  • createTimestring (date-time)read-only

    Create and update timestamps.

  • updateTimestring (date-time)read-only
  • deleteTimestring (date-time)read-only

    If present, the listing role has been deleted and won’t be returned in List operations.

  • displayNamestringrequired

    A short display name of the role. For example “Viewer”, “Editor”, or “Admin”.

  • descriptionstring

    A longer description of the role explaining to the end user when they would request this role over another role.

  • resourcesstring[]

    The set of resources that represent the role.

    When requesting a role, the target user, team, or group will be granted entitlements for all resources in this list, regardless of existing entitlements. For example, if a user has an entitlement for one resource out of two, they will be granted access to the second.

    Updating the list of resources does NOT change any entitlements that were granted through previous requests for this role. Removing a resource does NOT revoke access. Adding a resource does NOT grant access.

  • prioritystring (int64)required

    Priority indicates the order roles are displayed to the user. Generally roles with less access should be first (“Viewer”, “Editor”, “Admin”). Roles with lower priority values are displayed first. For example:

    • “Viewer” (priority = 0)
    • “Editor” (priority = 1)
    • “Admin” (priority = 2)
  • managementManagement

    How this role is managed. Inherited from the parent listing: roles of Terraform-managed listings are themselves Terraform managed and can only be created, updated, or deleted through the Terraform provider; manage the parent listing to change this. Omitted from responses when the parent listing is manually managed (the default).

    • managerstring
      Allowed values: TERRAFORM

      How the resource is managed. Set automatically by the server based on the caller: Terraform clients produce TERRAFORM; for all other clients the management field is left unset on the response.

    • repoUristring

      URI of the VCS repository that holds the Terraform configuration for this resource. Populated by the Oblique Terraform provider.

    • repoDirstring

      Optionally, the subdirectory within repo_uri that holds the Terraform configuration for this resource. Populated by the Oblique Terraform provider.

Errors

StatusMeaning
400Malformed request
401Missing or invalid API key
403Not allowed for this API key
404Not found
429Too many requests
500Internal server error