List and maintain role definitions
An administration service synchronizes application roles with Kinde.
Kinde · Module
Roles API
The Roles API lets applications manage Kinde roles and their organization-user assignments through the Management API. Roles package permissions into reusable groups, with access controlled by dedicated M2M token scopes.
How it works
The Roles API is part of Kinde’s Management API. An M2M application receives a JWT access token with role-related scopes, then sends that token as a Bearer credential to list, create, update, or delete roles and to manage roles assigned to organization users.
Syntax
GET /api/v1/rolesReturns
Role resources or operation-specific JSON responses from the Kinde Management API.
Key points
- A role is a reusable collection of permissions rather than a single permission.
- Management API requests use JWT access tokens for authentication.
- The read:roles scope authorizes reading role data.
- The create:roles scope authorizes creating roles.
- The update:roles scope authorizes changing existing roles.
- The delete:roles scope authorizes deleting roles.
- Organization-user role assignments have a dedicated read scope.
- A dedicated scope controls assigning roles to organization users.
Common mistakes
- The token must contain the scope required by the operation, such as read:roles or create:roles.
Example: List roles
const response = await fetch(`${KINDE_DOMAIN}/api/v1/roles`, {
headers: { Authorization: `Bearer ${M2M_ACCESS_TOKEN}` }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());Uses an M2M bearer token to request the roles collection from the Kinde Management API.
When to use it
Assign organization-user roles
An onboarding workflow grants a predefined role to a user in an organization.
Remove role assignments
A security workflow removes access when a user changes responsibilities.
Interview questions
QHow does an application access the Roles API?
Roles are managed through the Kinde Management API. The application authenticates with an M2M JWT and requests the relevant role scope, such as read:roles, create:roles, update:roles, or delete:roles.
Follow-up: How would you restrict access to only listing roles? Authorize the M2M application with read:roles and request a token containing only the needed scope.
QWhich capabilities does the Roles API provide?
The API supports role lifecycle operations: reading, creating, updating, and deleting roles. It also exposes separate operations for reading, assigning, and removing roles for organization users.
Follow-up: Why are organization-user role scopes separate? They govern assignments to users independently from managing the role definitions themselves.
QHow do roles relate to permissions and users?
Roles group permissions into reusable buckets, and a user may receive multiple roles. Permissions can also be assigned directly to a user in addition to role-derived permissions.
Follow-up: Where are roles defined and applied? They are defined at the business level and applied to users at the organization level.
Related
Kinde Management APIM2M access tokenread:rolescreate:rolesupdate:rolesdelete:rolesorganization_user_rolespermissions