Skip to main content

​
Permission

A permission is the smallest authorization unit in the RBAC model. Each permission grants access to a specific resource identified by its URL path. Permissions can be defined for either an organization owner or a workspace member. Organization owners implicitly possess all permissions granted to workspace members by default.   

​
Roles:

Organization Owners: A set of permissions specific to the owner of the organization. Organization owners implicitly possess all permissions granted to workspace members by default.   Workspace Members: A limited set of permissions defined for workspace members of the organization. Organization Owners can define, assign, and manage the permissions available to Workspace Members.   
                       +----------------------+
                       |     Permissions      |
                       |  (URL Path Access)   |
                       +----------+-----------+
                                  |
                 +----------------+----------------+
                 |                                 |
      +----------------------+          +----------------------+
      |   Workspace Member   |          |  Organization Owner  |
      +----------------------+          +----------------------+
      |  Subset of          |          |  Owner-specific      |
      |  permissions        |          |  permissions         |
      +----------------------+          +----------+-----------+
                                                    |
                                                    |  Automatically includes
                                                    |  all Workspace Member
                                                    |  permissions
                                                    v
                                          +----------------------+
                                          |  Full Permission Set |
                                          +----------------------+
    NOTE: RBAC must preserve pre-existing access rights for all user types by default.

​
Workspace Member Permission Management API

Enables organization owners to manage custom workspace roles, assign permissions, and control workspace member access.

​
Endpoints

​
Permissions

​
List Available Permissions of Organization owner

GET /v1/authorization/organizations/{orgId}/owner/permissions?name=&service=&audience=&page=1&limit=10
Returns permissions available to the organization owner — the pool from which you can build custom roles. Filter by name (partial match), service (exact), or audience ORGANIZATION_USER, WORKSPACE_USER). Max limit: 100.

​
Get Workspace User Permissions

GET /v1/authorization/organization/{orgId}/workspace/{workspaceId}/user/{userId}/permissions
Returns all roles and permissions assigned to a user within a specific workspace.

​
Add Permissions to Role

POST /v1/authorization/organizations/{orgId}/roles/{roleId}/permissions
{ "permissions": ["perm-id-1", "perm-id-2"] }
Adds permissions without affecting existing ones. Already-assigned permissions are skipped. Response includes affectedCoun/affectedPermissionIds and skippedCountskippedPermissionIds.

​
Revoke Permissions from Role

DELETE /v1/authorization/organizations/{orgId}/roles/{roleId}/permissions
{ "permissions": ["perm-id-1", "perm-id-2"] }
Removes specified permissions. Permissions not on the role are skipped. Same response format as add.

​
Roles

​
List Roles

GET /v1/authorization/organizations/{orgId}/roles?isSystemGenerated=&scope=&status=&page=1&limit=10
Returns all roles in the organization. Filter by isSystemGenerated (boolean), scope ORGANIZATIONWORKSPACE), or status ACTIVEINACTIVE). Max limit: 50.

​
Create Workspace Role — 201 Created

POST /v1/authorization/organizations/{orgId}/roles
{
  "name": "Call Analyst",
  "description": "Read-only access to call logs",
  "permissions": ["perm-id-1", "perm-id-2"]
}
name and description are required. permissions is optional and must be WORKSPACE_USER audience only. Role names cannot use reserved prefixes ORGANIZATION_OWNER, WORKSPACE_MEMBER).

​
Get Role Details

GET /v1/authorization/organizations/{orgId}/roles/{roleId}
Returns role metadata and its full list of assigned permissions.

​
Update Workspace Role

PUT /v1/authorization/organizations/{orgId}/roles/{roleId}
{
  "name": "Senior Analyst",
  "description": "Updated description",
  "status": "ACTIVE",
  "permissions": ["perm-id-1", "perm-id-3"]
}
All fields optional. **The permissions list replaces the entire permission set** — omitted permissions are removed. System-generated roles cannot be modified.

​
Delete Workspace Role — 204 No Content

DELETE /v1/authorization/organizations/{orgId}/roles/{roleId}
System-generated roles cannot be deleted.

​
Workspace Member Role Assignment

​
Change Workspace Member Role

PUT /v1/authorization/organizations/{orgId}/workspaces/{workspaceId}/members/{userId}/role
{ "roleId": "role-uuid" }
Replaces a user’s role in a workspace. The role must be active, belong to the organization, and have WORKSPACE scope. Idempotent — returns success if the user already has the requested role.

​
Onboarding Users with proper role-permission

These endpoints are called by the Identity Service during user and workspace onboarding flows.

​
Onboard Organization Owner — 201 Created

POST /v1/authorization/onboarding/organization-owner-role
{
  "org_id": "org-uuid",
  "user_id": "user-uuid"
}
Called automatically when a new user signs up and creates an organization. Creates the ORGANIZATION_OWNER role for the organization and assigns it to the user with all default permissions. This is a one-time setup per organization — subsequent calls for the same organization will fail.

​
Onboard Workspace Member — 201 Created

POST /v1/authorization/onboarding/workspace-member-role
{
  "org_id": "org-uuid",
  "workspace_id": "ws-uuid",
  "user_id": "user-uuid",
  "role_id": "custom-role-uuid",
  "save_as_default": false
}
Called when an invited user accepts a workspace invitation. Assigns a role to the user in the workspace.
  • If role_id is omitted, the workspace’s default role is used (or an org-level default is created automatically)
  • If role_id is provided, that custom role is assigned instead
  • Set save_as_default: true with a role_id to make it the default role for future members of this workspace

​
Authorization Check

These endpoints are used by the API Gateway to verify whether a user has permission to access a specific resource.

​
Check Permission by Verbex ID

POST /v1/authorization/verbex/identity
{
  "verbex_id": "oauth-subject-id",
  "org_id": "org-uuid",
  "workspace_id": "ws-uuid",
  "url_path": "/v1/agents/{id}",
  "method": "GET"
}
Resolves the Verbex ID (OAuth subject) to an internal user and checks if the user has permission to access the given URL path and method. workspace_id is optional — omit it for organization-level resource checks.

​
Check Permission by User ID

POST /v1/authorization/user/identity
{
  "user_id": "user-uuid",
  "org_id": "org-uuid",
  "workspace_id": "ws-uuid",
  "url_path": "/v1/agents/{id}",
  "method": "GET"
}
Same as above but uses the internal user ID directly instead of resolving from a Verbex ID. Same response format.

​
Errors

StatusWhen
400Invalid input or reserved role name
403Modifying/deleting a system-generated role, or user lacks permission for the requested resource
404Role, permission, or workspace not found
409Duplicate role name in the organization