Roles and permissions

Permissions

curl -X POST https://api.unkey.com/v2/permissions.createPermission \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Read documents", "slug": "documents.read", "description": "List and fetch documents" }'

• permissions.getPermission takes the ID or slug.
• permissions.listPermissions takes limit (1 to 100, default 100), cursor (up to 1024 characters), and search (up to 256 characters, matched against ID, name, slug, or description, ignoring case).
• permissions.updatePermission takes the ID or slug in permission, plus any of name, slug, and description. Omitted fields stay unchanged, and description: null removes the description. It needs unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#write. A slug that another permission already uses fails with HTTP 409. Keys and roles keep the permission after a slug change. Key verification can return the old slug for a short time while caches refresh.
• permissions.deletePermission deletes the permission and removes it from every role and key. It needs unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/<permission_id>#delete.

Roles

curl -X POST https://api.unkey.com/v2/permissions.createRole \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Read and write documents",
    "permissions": ["documents.read", "documents.write"]
  }'

Change a role’s permissions

curl -X POST https://api.unkey.com/v2/permissions.setRolePermissions \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "editor", "permissions": ["documents.read", "documents.write", "documents.delete"] }'

Designing the set

• Name permissions after actions, not customers: invoices.read, invoices.write, invoices.void.
• Name roles the way you talk to customers: viewer, editor, admin, or plan names.
• Attach roles to keys, and save direct permissions for one-off grants. Then changing what “editor” means is one setRolePermissions call, not an update to every key.
• Use a role for “everything under documents”. An asterisk isn’t a wildcard, so list each documents.* permission in the role.

From the dashboard