API Reference

Roles & Permissions

Database-driven RBAC system for managing roles and permissions at tenant and platform levels.

The Roles & Permissions API provides full CRUD for tenant-scoped roles and a read-only endpoint for the global permission registry. Permissions are stored in the database and resolved at runtime - no hardcoded role-permission mappings.

Every user must have a roleId assigned. Users without a role will receive a 403 Forbidden response on any permission-protected endpoint.

Role Endpoints

Method	Endpoint	Permission	Description
GET	/roles	role:read	List all roles for the current tenant
GET	/roles/:id	role:read	Get role details with permissions
POST	/roles	role:create	Create a new custom role
PUT	/roles/:id	role:update	Update role name, description, or permissions
DELETE	/roles/:id	role:delete	Delete a custom role (system roles protected)

Permission Endpoints

Method	Endpoint	Permission	Description
GET	/permissions	role:read	List all available permissions grouped by resource

GET /roles - List Roles

Returns all roles for the authenticated tenant, including assigned permissions and user count.

bash

curl https://mayaapi.teamcast.ai/api/v1/roles \
  -H "Authorization: Bearer <jwt>"

json

{
  "roles": [
    {
      "id": "uuid",
      "name": "Admin",
      "description": "Full access to all tenant resources",
      "isSystem": true,
      "permissions": [
        {
          "id": "uuid",
          "code": "interview:create",
          "resource": "interview",
          "action": "create",
          "description": "Create new interviews"
        }
      ],
      "userCount": 2,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 3
}

POST /roles - Create Role

Create a custom role with a set of permission codes. The role name must be unique within the tenant.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/roles \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hiring Manager",
    "description": "Can view and approve interview plans",
    "permissionCodes": [
      "interview:read",
      "interview:approve",
      "user:read",
      "role:read"
    ]
  }'

Field	Type	Required	Description
name	string	Yes	Role name (unique per tenant, max 100 chars)
description	string	No	Role description (max 500 chars)
permissionCodes	string[]	Yes	Array of valid permission codes (min 1)

PUT /roles/:id - Update Role

Update a role name, description, or replace its permission set. All fields are optional. When permissionCodes is provided, the entire permission set is replaced (not merged).

bash

curl -X PUT https://mayaapi.teamcast.ai/api/v1/roles/<role-id> \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionCodes": [
      "interview:read",
      "interview:approve",
      "interview:assess",
      "user:read",
      "role:read"
    ]
  }'

DELETE /roles/:id - Delete Role

Delete a custom role. System roles (Admin, Recruiter, User) cannot be deleted. Roles with assigned users must have their users reassigned first.

bash

curl -X DELETE https://mayaapi.teamcast.ai/api/v1/roles/<role-id> \
  -H "Authorization: Bearer <admin-jwt>"

Returns 400 if the role is a system role or has users still assigned to it.

GET /permissions - List Permissions

Returns all available permissions grouped by resource. Use this to populate the permission assignment UI when creating or editing roles.

bash

curl https://mayaapi.teamcast.ai/api/v1/permissions \
  -H "Authorization: Bearer <jwt>"

json

{
  "groups": [
    {
      "resource": "interview",
      "permissions": [
        { "id": "uuid", "code": "interview:create", "resource": "interview", "action": "create", "description": "Create new interviews" },
        { "id": "uuid", "code": "interview:read", "resource": "interview", "action": "read", "description": "View interviews" },
        { "id": "uuid", "code": "interview:update", "resource": "interview", "action": "update", "description": "Update interview details" },
        { "id": "uuid", "code": "interview:delete", "resource": "interview", "action": "delete", "description": "Delete interviews" },
        { "id": "uuid", "code": "interview:approve", "resource": "interview", "action": "approve", "description": "Approve or reject interview plans" },
        { "id": "uuid", "code": "interview:conduct", "resource": "interview", "action": "conduct", "description": "Conduct live interviews" },
        { "id": "uuid", "code": "interview:assess", "resource": "interview", "action": "assess", "description": "Trigger and view assessments" }
      ]
    },
    {
      "resource": "user",
      "permissions": [ ... ]
    }
  ],
  "total": 28
}

Permission Codes Reference

Resource	Code	Description
interview	interview:create	Create new interviews
interview	interview:read	View interviews
interview	interview:update	Update interview details
interview	interview:delete	Delete interviews
interview	interview:approve	Approve or reject interview plans
interview	interview:conduct	Conduct live interviews
interview	interview:assess	Trigger and view assessments
tenant	tenant:create	Create new tenants
tenant	tenant:read	View tenant information
tenant	tenant:update	Update tenant settings
tenant	tenant:delete	Delete tenants
user	user:create	Create new users
user	user:read	View user information
user	user:update	Update user profiles
user	user:delete	Delete users
apikey	apikey:create	Create API keys
apikey	apikey:read	View API keys
apikey	apikey:delete	Delete API keys
oauth	oauth:create	Create OAuth clients
oauth	oauth:read	View OAuth clients
oauth	oauth:delete	Delete OAuth clients
webhook	webhook:read	View webhook configuration
webhook	webhook:update	Update webhook configuration
system	system:monitor	View system health and monitoring
role	role:create	Create new roles
role	role:read	View roles and permissions
role	role:update	Update roles and assign permissions
role	role:delete	Delete custom roles

User Role Assignment

When creating or updating a user, pass the roleId field to assign a database-managed role. The legacy role enum field is still accepted for backward compatibility.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/users \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "manager@example.com",
    "password": "SecurePass123!",
    "firstName": "Hiring",
    "lastName": "Manager",
    "role": "user",
    "roleId": "<tenant-role-uuid>"
  }'

If roleId is provided, the permission guard resolves permissions from the database role. If omitted, the system auto-resolves the roleId from the default role matching the enum name.

API Key Integration (X-User-ID)

API key requests can optionally include an X-User-ID header to identify which user is performing the action. This is used for audit trails only - permission checks for API keys still use the key's own permission set.

bash

curl https://mayaapi.teamcast.ai/api/v1/interviews \
  -H "X-API-Key: sk_live_..." \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "X-User-ID: <user-id>"

Was this page helpful?

Previous← Users & Tenants

NextAPI Keys & OAuth →