Get a list of roles

get

https://api.entitle.io/public/v1/roles

Returns a paginated list of roles. Scope the results with either resourceId (roles of a single resource) or integrationId (every role across all resources of an integration, in one paginated response — use this to avoid issuing one request per resource). At least one of the two is required; if both are provided, resourceId takes precedence. Optionally filter by externalId or search, or narrow the results with ids (with idsOperator), requestable, workflowId (with workflowIdOperator), resourceType and resourceTags. All filters are combined with AND. search cannot be combined with these filters unless externalId is provided. To read the whole list reliably, page with afterId instead of page.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

page

number

≥ 1

Defaults to 1

perPage

number

1 to 100

Defaults to 100

afterId

uuid

Cursor for reading the whole list without skipping or repeating items while it changes. Results are sorted by id, so pass the id of the last item of the previous page to get the items after it, and stop when a page returns fewer than perPage items. totalResults then counts only the items after afterId. Cannot be combined with a page other than 1 or with search.

string

Search roles by name. Exact matches are ranked first, followed by case-insensitive and partial matches.

externalId

string

Filter roles by external identifier (the ID given by the third-party app, e.g. AWS, GitHub).

resourceId

uuid

Unique identifier for the resource. Provide either resourceId or integrationId. To get resource IDs, use GET /public/v1/resources?integrationId=.

integrationId

uuid

Filter roles by integration. Returns every role across all resources in the integration in a single paginated response. Provide either resourceId or integrationId. To get integration IDs, use GET /public/v1/integrations.

ids

array of uuids

Filter roles by ID, up to 100 IDs. Accepts a comma-separated list or a repeated parameter. Cannot be combined with search unless externalId is provided.

ids

idsOperator

string

enum

Defaults to is

How ids is matched: is returns the given roles, isNot returns every role except them. Requires ids.

Allowed:

requestable

boolean

Filter roles by whether they are requestable. Cannot be combined with search unless externalId is provided.

workflowId

array of uuids or null

Filter roles by workflow ID. Accepts a comma-separated list or a repeated parameter. Use null to match roles with no workflow of their own. Cannot be combined with search unless externalId is provided. To get workflow IDs, use GET /public/v1/workflows.

workflowId

workflowIdOperator

string

enum

Defaults to is

How workflowId is matched: is returns roles with one of the given workflows, isNot returns roles with none of them. Requires workflowId.

Allowed:

resourceType

array of strings

Filter roles by the type of their resource. Accepts a comma-separated list or a repeated parameter. Cannot be combined with search unless externalId is provided.

resourceType

resourceTypeOperator

string

enum

Defaults to is

How resourceType is matched: is (default) returns roles whose resource type is one of the values, isNot returns roles whose resource type is none of them, contains returns roles whose resource type contains any of the values, notContains returns roles whose resource type contains none of them. Requires resourceType.

Allowed:

resourceTags

array of strings

Filter roles by the tags of their resource. Returns roles whose resource has at least one of the given tags. Accepts a comma-separated list or a repeated parameter. Cannot be combined with search unless externalId is provided.

resourceTags

resourceTagsOperator

string

enum

Defaults to is

How resourceTags is matched: is (default) returns roles whose resource has the tags, isNot returns roles whose resource does not have them, including resources with no tags. Combined with resourceTagsRelation. Requires resourceTags.

Allowed:

resourceTagsRelation

string

enum

Defaults to or

How multiple resourceTags values are combined. With is: or (default) matches resources that have any of the tags, and matches resources that have all of them. With isNot: or (default) matches resources that have none of the tags, and matches resources that are missing at least one of them. Requires resourceTags.

Allowed:

Response

200