Get Role

Auto-generate your docs

Retrieve details about a specific role including its assigned permissions.

Required Permissions

Your root key must have the following permission:

rbac.*.read_role

Request

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

string

required

The unique identifier for this role.

string

required

The role name.

string

Description of what this role grants access to.

array

Array of permissions assigned to this role.Each permission includes:

id: Permission identifier
name: Permission name

integer

Unix timestamp in milliseconds when the role was created.

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"
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

const result = await unkey.permissions.getRole({
  role: "role_1234567890abcdef",
});

console.log(result.result);

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
  }
}

Overview

Keys

APIs

Rate Limiting

Identities

Analytics

Permissions

Required Permissions

Request

Response

Examples

Response Example

​Required Permissions

​Request

​Response

​Examples

​Response Example

Required Permissions

Request

Response

Examples

Response Example