Scripe
SCRIPEDOCS

Role & Permission API

Role CRUD, permission assignment, tenant-scoped roles, and permission catalog for RBAC management.

The Role & Permission API manages the RBAC (Role-Based Access Control) system. Roles are tenant-scoped, meaning each tenant has its own set of roles. Permissions are seeded from the backend and are read-only. Roles compose permissions with optional field-level restrictions.

Role CRUD

MethodEndpointDescriptionAuth
GET/api/v1/rolesList all roles in the current tenant with admin counts.🔒 Required
GET/api/v1/roles/{id}Get role details including permissions, menu items, and field restrictions.🔒 Required
POST/api/v1/rolesCreate a new custom role with permissions and menu visibility.🔒 Required
PUT/api/v1/roles/{id}Update role name, description, and menu visibility.🔒 Required
DELETE/api/v1/roles/{id}Delete a role. Fails if admins are still assigned to it.🔒 Required
POST/api/v1/roles/{id}/cloneClone an existing role with all its permissions and menu items.🔒 Required
GET /roles/{id} — ResponseJSON
{
  "id": "role-uuid",
  "name": "Branch Manager",
  "description": "Manager for branch offices",
  "isDefault": false,
  "isSystem": false,
  "adminCount": 5,
  "permissions": [
    {
      "id": "perm-uuid",
      "name": "admins.view",
      "category": "Admin Management",
      "restrictedFields": ["email", "phoneNumber"]
    }
  ],
  "menuItems": [
    { "id": "menu-uuid", "title": "Dashboard", "isVisible": true }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}

Permission Assignment

MethodEndpointDescriptionAuth
PUT/api/v1/roles/{id}/permissionsReplace all permissions for a role. Supports field-level restrictions per permission.🔒 Required
GET/api/v1/roles/{id}/permissionsGet the current permissions assigned to a role.🔒 Required
POST/api/v1/roles/{id}/sync-scopesSync permission scopes and restricted fields from the parent tenant.🔒 Required
PUT /roles/{id}/permissions — Assign PermissionsJSON
// Request: Replace all permissions for this role
{
  "permissionIds": [
    "perm-admins-view",
    "perm-admins-create",
    "perm-users-view",
    "perm-dashboard-view"
  ],
  "restrictedFields": {
    "perm-admins-view": ["email", "phoneNumber", "lastLoginIp"],
    "perm-users-view": ["email"]
  }
}

// Response (200)
{
  "message": "Permissions updated",
  "totalPermissions": 4,
  "restrictedFieldsCount": 2
}

Tenant-Scoped Roles

Each tenant has its own set of roles that can only use permissions available in the tenant's scope. The available permissions are controlled by the parent tenant's role assignment. Admins can only see and assign permissions their tenant is allowed to use.

MethodEndpointDescriptionAuth
GET/api/v1/roles/my-tenant-rolesList roles available in the current admin's tenant.🔒 Required
GET/api/v1/roles/my-tenant-available-permissionsList permissions available for assignment in the current tenant's scope.🔒 Required

Permissions (Read-Only)

Permissions are seeded automatically from the backend. They cannot be created or modified through the API. Each permission belongs to a category and can have field-level restrictions when assigned to a role.

MethodEndpointDescriptionAuth
GET/api/v1/permissionsList all permissions grouped by category.🔒 Required
GET/api/v1/permissions/myGet the current admin's effective permissions.🔒 Required
GET/api/v1/permissions/{id}Get a single permission by ID with full details.🔒 Required
GET/api/v1/permissions/categoriesGet permission categories with all permissions in each.🔒 Required
GET/api/v1/permissions/available-for-tenantList permissions available for a specific tenant (for tenant creation/editing).🔒 Required
GET /permissions/categories — ResponseJSON
[
  {
    "name": "Admin Management",
    "slug": "admins",
    "permissions": [
      { "id": "p1", "name": "admins.view", "description": "View admin list" },
      { "id": "p2", "name": "admins.create", "description": "Create new admins" },
      { "id": "p3", "name": "admins.update", "description": "Update admin details" },
      { "id": "p4", "name": "admins.delete", "description": "Delete admins" }
    ]
  },
  {
    "name": "User Management",
    "slug": "users",
    "permissions": [
      { "id": "p5", "name": "users.view", "description": "View user list" },
      { "id": "p6", "name": "users.create", "description": "Register users" }
    ]
  }
]
PreviousTenant Management APINextUser Groups API