> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RBAC Guideline

### **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. 

 

### **Role**s:

**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

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