Roles & Permissions API
Manage role-based access control within a tenant. Create roles, assign permission sets, and perform real-time authorization checks.
Base URL: https://id.vyntech.com.au/api/v1 — All endpoints require authentication. Role management requires roles:manage permission.
List Roles
Returns all roles defined within the tenant, including their permission sets.
/api/v1/roles🔒 AuthList all roles in the current tenant.
Create Role
Creates a new role within the tenant. Role names must be unique within the tenant. Permissions are specified as an array of resource:action strings.
/api/v1/roles🔒 AuthCreate a new role with specified permissions.
{
"name": "billing-admin",
"description": "Manage billing and invoices",
"permissions": ["billing:read", "billing:write", "invoices:read", "invoices:write"]
}Get Role
Returns a specific role by ID, including its permissions and user count.
/api/v1/roles/:id🔒 AuthGet a specific role by ID.
Update Role
Updates a role's name, description, or permissions. Users with this role will get updated permissions on their next token refresh.
/api/v1/roles/:id🔒 AuthUpdate a role's details and permissions.
{
"name": "admin",
"description": "Full administrative access (updated)",
"permissions": ["users:read", "users:write", "roles:manage", "settings:write", "billing:read"]
}Delete Role
Deletes a role. All users with this role will have it removed. Cannot delete a role that is the tenant's only admin role (safety check).
/api/v1/roles/:id🔒 AuthDelete a role and unassign from all users.
Set Role Permissions
Replaces the entire permission set for a role. This is a full replacement — any permissions not included in the array will be removed.
/api/v1/roles/:id/permissions🔒 AuthReplace all permissions for a role.
{
"permissions": ["posts:read", "posts:write", "posts:publish", "media:upload", "media:delete"]
}List Available Permissions
Returns the full list of available permissions that can be assigned to roles. Permissions follow the resource:action format.
/api/v1/permissions🔒 AuthList all available permissions.
Authorization Check
Performs a real-time authorization check against the user's roles, permissions, and Cedar policies. Use this when your backend needs to make a complex access decision that goes beyond simple JWT permission checks.
/api/v1/authz/check🔒 AuthCheck if a user is authorized for a specific action on a resource.
{
"user_id": "usr_01H8KXYZ4F2B7NQ9RPWT3M6J",
"action": "write",
"resource": "posts",
"context": {
"department": "engineering",
"post_status": "draft"
}
}