Roles & Permissions

Kapable uses role-based access control (RBAC) to manage what members can do within your organisation. This guide explains the built-in roles, how to create custom roles, and best practices for access management.

Built-in Roles

Every organisation comes with four built-in roles:

Owner

The organisation creator. Full access to everything.

Manage billing and subscription
Delete the organisation
Manage all members and roles
Configure authentication settings
Full app and deployment control
Access all audit logs

There is exactly one owner per organisation. Ownership can be transferred but not shared.

Admin

Trusted team leads with broad access, but no billing or destructive org controls.

Invite and manage members
Create and manage apps
Deploy and configure apps
Manage agents, mailboxes, and tokens
View audit logs
Configure auth settings (if permitted)

Member

Standard team members who build and deploy.

Create apps
Deploy to their own apps
View app logs and settings
Manage their own API keys
View team members (read-only)
Access documentation

Viewer

Read-only access for stakeholders and observers.

View apps and their status
View deployment history
View team members
Access documentation
Cannot create, modify, or deploy anything

Permission Matrix

Action	Owner	Admin	Member	Viewer
Organisation
View org info	Yes	Yes	Yes	Yes
Edit org name/slug	Yes	Yes	No	No
Delete organisation	Yes	No	No	No
Manage billing	Yes	No	No	No
Members
View members	Yes	Yes	Yes	Yes
Invite members	Yes	Yes	No	No
Remove members	Yes	Yes	No	No
Change member roles	Yes	Yes	No	No
Apps
View apps	Yes	Yes	Yes	Yes
Create apps	Yes	Yes	Yes	No
Deploy apps	Yes	Yes	Yes	No
Delete apps	Yes	Yes	No	No
Manage app settings	Yes	Yes	Yes	No
Manage custom domains	Yes	Yes	No	No
Auth & Security
View audit log	Yes	Yes	No	No
Configure SSO	Yes	Yes	No	No
Manage domain allowlist	Yes	Yes	No	No
Communications
View agents	Yes	Yes	Yes	Yes
Create agents	Yes	Yes	Yes	No
Manage agent keys	Yes	Yes	Yes	No
View send audit	Yes	Yes	Yes	No
API Keys
Create own API keys	Yes	Yes	Yes	No
Revoke own API keys	Yes	Yes	Yes	No
View all API keys	Yes	Yes	No	No
Revoke others' keys	Yes	Yes	No	No

Custom Roles

Organisations on paid plans can create custom roles with fine-grained permissions.

Creating a Custom Role

Navigate to Roles in your console sidebar
Click Create Role
Enter a role name and description
Select permissions from the available list
Save the role

Assigning Custom Roles

Once created, custom roles appear in the role dropdown when:

Inviting new members
Changing an existing member's role

Editing and Deleting

Edit a custom role's permissions at any time — changes apply to all members with that role immediately
Deleting a custom role reassigns affected members to the Member built-in role
Built-in roles cannot be edited or deleted

Role-Based Access in the API

When using the API with a session token or API key, the caller's role determines what endpoints succeed:

# This succeeds for Owner/Admin
POST /v1/orgs/{org_id}/invitations
Authorization: Bearer kses_...

# This fails for Member/Viewer with 403 Forbidden
POST /v1/orgs/{org_id}/invitations
Authorization: Bearer kses_...
{"error": "insufficient permissions"}

The API returns 403 Forbidden for any action the caller's role doesn't permit.