get_role¶

ManagementApi.get_role(id, role_id, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Get role details

Returns the full detail of a single role, including RoleConsolidatedPermissions: the effective permission set after expanding the transitive dependencies of RolePermissions. That field is always computed and cannot be requested or suppressed. The caller must be attached to the role or be one of its role managers, unless the request carries Super Admin context. Note that an unknown role id is reported as HTTP 500, not 404 or 400, because the handler raises it as a backend exception.

Parameters:

id (str) – Identifier of the role, in the form “role-<uuid>”. (required)
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. The backend applies no floor to this reduction, so any attribute can be omitted from the response, including RoleId.
_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:

RoleMetadata

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /roles/{id}

Parameter examples¶

Name	In	Example
`id`	path	`"role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"`
`role_id`	header	`"role-admin"`
`projectionExpression`	query	`"RoleId,RoleName,RoleConsolidatedPermissions"`

Success (HTTP 200)¶

Role details.

Full role detail

{
  "RoleId": "role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "RoleName": "data-analyst",
  "RoleDescription": "Read access to sales datasets",
  "RolePermissions": [
    "datasets.view",
    "playground.manage"
  ],
  "RoleConsolidatedPermissions": [
    "datasets.view",
    "domains.view",
    "playground.manage",
    "playground.view"
  ],
  "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"
}

Reduced by projectionExpression

{
  "RoleId": "role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "RoleName": "data-analyst"
}

Errors¶

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

HTTP 400

Authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AUTH-1011 (the caller is neither attached to the role nor a role manager), AUTH-1001 / AUTH-1003 / AUTH-1030 / IPV-1002 (authorization on the role_id header), GE-1008 (a stored permission entry could not be parsed).

Caller is not attached to the role

{
  "Message": "AUTH-1011 - User user2 is not authorized to view resource details"
}

role_id header absent

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

HTTP 500

Backend failure. Also returned when the role id in the path does not exist: the handler raises IPV-1002 as a backend exception, so a missing role surfaces here rather than as a 400 or 404. Body is {“Message”: “<CODE> - <text>”}.

Role id does not exist

{
  "Message": "IPV-1002 - Invalid RoleId - role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f, resource not found."
}

Generic backend failure

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