Role-Based Access Control (RBAC)

VoxKey implements RBAC through API Resources, Scopes, and Roles. This lets you control what users and applications can access in your APIs.

Data model

API Resources

An API Resource represents a protected API in your system. Each resource has:

• Name -- human-readable label (e.g. "Blog API")
• Indicator -- audience URI used in token requests (e.g. https://api.example.com)
• Access Token TTL -- token lifetime in seconds for this resource
• Scopes -- permissions belonging to this resource

Request tokens for a specific resource using the resource parameter:

curl -X POST https://auth.example.com/oauth2/{realmUUID}/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET \
  -d scope="read:posts write:posts" \
  -d resource=https://api.example.com

Scopes

Scopes are permissions attached to an API Resource. They appear in JWT access tokens as the scope claim.

Built-in OIDC scopes (always available):

• openid -- required for OIDC flows
• profile -- user name and metadata
• email -- user email address
• phone -- user phone number
• offline_access -- issue refresh tokens

Custom scopes are defined per API Resource (e.g. read:posts, admin:users).

Roles

Roles group scopes together and are assigned to users or applications.

Two role types:

Type	Assigned to	Use case
user	Realm users	End-user permissions (viewer, editor, admin)
m2m	Applications	Machine-to-machine service permissions

A role can include scopes from multiple API Resources.

Management API

Every realm gets a built-in Management API resource with these scopes:

Scope	Description
all	Full access to all endpoints
users:read	View users
users:write	Create, update, delete users
users:roles	Manage user role assignments
applications:read	View applications
applications:write	Create, update, delete applications
roles:read	View roles
roles:write	Create, update, delete roles
resources:read	View API resources
resources:write	Create, update, delete API resources
providers:read	View auth providers
providers:write	Manage auth providers
settings:read	View realm settings
settings:write	Update realm settings
logs:read	View audit logs

How tokens carry permissions

When a user or M2M app requests a token, VoxKey resolves their roles, collects all granted scopes, intersects with the requested scopes, and embeds them in the JWT:

{
  "sub": "user_abc123",
  "aud": "https://api.example.com",
  "scope": "read:posts write:posts",
  "iss": "https://auth.example.com/oauth2/{realmUUID}",
  "exp": 1711612800
}

Setting up RBAC

1. Create an API Resource -- define your API's audience URI and scopes
2. Create Roles -- group scopes into logical roles
3. Assign Roles -- assign roles to users or M2M applications
4. Validate in your API -- check the scope claim in incoming JWTs