ListListingRoles

GET/api/v1/listings/{listing}/roles

List or search for roles that a user, group, or team can gain access to. ListingRoles represent roles within applications, such as “Salesforce - Admin”.

To determine the set of roles a user has, use ListListingRoleEffectiveSubjects.

Example request

US
Europe

curl \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  "https://us.oblique.security/api/v1/listings/{listing}/roles"

Set OBLIQUE_API_KEY to your API key.

curl \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  "https://eu.oblique.security/api/v1/listings/{listing}/roles"

Set OBLIQUE_API_KEY to your API key.

Path parameters

parentstringrequired
The parent of the listing roles. Can also be listings/- to list all listing roles. If listings/- is used, all roles for soft-deleted listings are omitted.

Format: listings/{listing}

Query parameters

pageSizeinteger (int32)
The maximum number of roles to return. This service may return fewer than this value.
pageTokenstring
A page token, received from a previous ListListingRoles call.
showDeletedboolean
If true, include deleted listing roles in the response.

Response

200ListListingRolesResponse

listingRolesListingRole[]
- 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.
nextPageTokenstring
A token, which can be sent as page_token to retrieve the next page.

Errors

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