Skip to main content
Retrieve details about a specific role including its assigned permissions.

​
Required Permissions

Your root key must have the following permission:
  • rbac.*.read_role

​
Request

​
role
string
required
Unique identifier of the role to retrieve.Must either be a valid role ID that begins with ‘role_’ or the given role name and exists within your workspace.Use this endpoint to verify role details, check its current permissions, or retrieve metadata.Returns complete role information including all assigned permissions for comprehensive access review.Pattern: ^[a-zA-Z0-9_:\-\.\*]+$Length: 3-255 charactersExample: role_1234567890abcdef or admin.billing

​
Response

​
id
string
required
The unique identifier for this role.
​
name
string
required
The role name.
​
description
string
Description of what this role grants access to.
​
permissions
array
Array of permissions assigned to this role.Each permission includes:
  • id: Permission identifier
  • name: Permission name
​
createdAt
integer
Unix timestamp in milliseconds when the role was created.
​
updatedAt
integer
Unix timestamp in milliseconds when the role was last updated.

​
Examples

curl -X POST https://api.unkey.com/v2/permissions.getRole \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "role_1234567890abcdef"
  }'

​
Response Example

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": {
    "id": "role_1234567890abcdef",
    "name": "admin.billing",
    "description": "Full access to billing and subscription management",
    "permissions": [
      {
        "id": "perm_123",
        "name": "billing.read"
      },
      {
        "id": "perm_124",
        "name": "billing.write"
      }
    ],
    "createdAt": 1704067200000,
    "updatedAt": 1704153600000
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us