list_roles

ManagementApi.list_roles(role_id, projection_expression=None, filter_expression=None, limit=None, offset=None, sortorder=None, sortby=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List roles

Returns a paginated list of roles. A Super Admin sees every role on the platform; any other caller sees only the roles they are attached to. Pagination: read next_available in the response. While it is “yes”, request the next page by advancing offset by limit. When it is “no” this was the last page and the client must stop. total_count is the number of roles matching the filter and count is the size of the current page.

Parameters:

• role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. Not required when the request carries Super Admin context. (required)

• projection_expression (str) – Comma-separated list of attributes to return for each role. Applied to the items inside roles only; the pagination keys are always returned in full.

• filter_expression (str) – Substring filter applied to RoleName. Only roles whose name matches are returned, and total_count reflects the filtered set.

• limit (str) – Maximum number of roles to return in one page. Values above 1000 are rejected with IPV-1050.

• offset (str) – One-based index of the first record to return. Non-numeric values cause the request to fail with HTTP 500, so always send a positive integer.

• sortorder (str) – Direction to sort by. Only the exact value “desc” sorts descending; the backend treats every other value as ascending rather than rejecting it.

• sortby (str) – Role attribute to sort by. The backend does not validate this value: naming an attribute that is missing from any role, or one whose value is not a string, causes the request to fail with HTTP 500. Prefer one of the listed values.

• _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

• _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

• _content_type (str, Optional) – force content-type for the request.

• _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

• _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

RoleDetailsList

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /roles

Parameter examples

Name	In	Example
role_id	header	"role-admin"
projectionExpression	query	"RoleId,RoleName,RoleDescription"
filterExpression	query	"analyst"
limit	query	"100"
offset	query	"1"
sortorder	query	"desc"
sortby	query	"LastModifiedTime"

Success (HTTP 200)

Page of roles. Check next_available to decide whether to request a further page.

First page with further pages available

{
  "roles": [
    {
      "RoleId": "role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "RoleName": "data-analyst",
      "RoleDescription": "Read access to sales datasets",
      "RolePermissions": [
        "datasets.view",
        "playground.manage"
      ],
      "UsersAttached": [
        "user1",
        "user2"
      ],
      "RoleManagers": [
        "user1"
      ],
      "CreationTime": "2025-01-15 10:30:00",
      "CreatedBy": "user1",
      "LastModifiedTime": "2025-06-01 14:22:00",
      "LastModifiedBy": "user1",
      "RoleVersion": "v3"
    },
    {
      "RoleId": "role-c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "RoleName": "data-engineer",
      "RoleDescription": "Manage datasets and pipelines",
      "RolePermissions": [
        "datasets.fullaccess"
      ],
      "UsersAttached": [
        "user3"
      ],
      "RoleManagers": [
        "user3"
      ],
      "CreationTime": "2025-02-02 08:10:00",
      "CreatedBy": "user3",
      "LastModifiedTime": "2025-05-20 09:05:00",
      "LastModifiedBy": "user3",
      "RoleVersion": "v3"
    }
  ],
  "next_available": "yes",
  "count": 2,
  "total_count": 63
}

Reduced by projectionExpression

{
  "roles": [
    {
      "RoleId": "role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "RoleName": "data-analyst"
    },
    {
      "RoleId": "role-c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "RoleName": "data-engineer"
    }
  ],
  "next_available": "no",
  "count": 2,
  "total_count": 2
}

Errors

Documented error codes: IPV-1050, AUTH-1001, AUTH-1003, AUTH-1030, IPV-1002, GE-1008.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1050 (limit above 1000), AUTH-1001 (role_id header missing), AUTH-1003 (caller not attached to the role), AUTH-1030 (role lacks the required permission), IPV-1002 (role_id header names an unknown role).

limit above the maximum of 1000

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 1000"
}

role_id header absent

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Role lacks the required permission

{
  "Message": "AUTH-1030 - User does not have required permissions to perform this operation"
}

HTTP 500

Backend failure. Also returned for a non-numeric offset or limit, and for a sortby naming an attribute that is missing from some role or is not a string. Body is {“Message”: “<CODE> - <text>”}.

Request / response example

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}