UNunkeyed
permissions

Get role

Changed on

Retrieve details about a specific role including its assigned permissions.

Required Permissions

Your root key must have the following permission:

  • rbac.*.read_role
post/v2/permissions.getRole

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/permissions.getRole
  • Auth
    HTTP bearer

Request body

rolestring required

Unique identifier of the role to permanently delete from your workspace. 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.

Example request

{
  "role": "role_1234567890abcdef"
}

Response

Role retrieved successfully

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "role_1234567890abcdef",
    "name": "support.readonly",
    "description": "Provides read-only access for customer support representatives to view user accounts and support tickets",
    "permissions": [
      {
        "id": "perm_1234567890abcdef",
        "name": "users.read",
        "slug": "users-read",
        "description": "Allows reading user profile information and account details"
      }
    ]
  }
}

Changes

  • 4bd11a7252bcRevision changes
    • breaking

      the request property's maxLength was decreased to 128

    • info

      the request property's minLength was decreased from 3 to 1

    • info

      removed the pattern ^[a-zA-Z0-9_:\-\.\*]+$ from the request property

  • 43ad1ce9a152Revision changes
    • info

      the endpoint scheme security bearer was added to the API

    • info

      the endpoint scheme security rootKey was removed from the API