Skip to content

RBAC

Manage roles and the permission catalog for an organisation.

Base URL

BASE_URL = "https://api.fermi.dev/public/v1/identity"

Authentication

Authorization: Bearer <service-actor-token>

Exchange an API key for a service-actor token with POST /public/v1/identity/auth/token/exchange. The organisation comes from that token. Clients cannot choose another organisation.

An API key (fmk_live_...) is not accepted on these routes. GET /public/v1/identity/roles with an API key returns:

{ "message": "Unauthorized", "statusCode": 401 }

The same key returns 200 on GET /public/v1/identity/service-actors. Create the service actor with the API key, exchange it, then call these routes with the service-actor token.

GET /roles/permissions-catalog is the list of scopes you can put on a role (tasks.view, connector.manage, and the rest). Those strings are Fermi module permissions. They are not the service actor's capabilities.

Permission catalog

GET /roles/permissions-catalog

Returns the modules a role can grant. Baseline access (Fermi chat) is omitted because every member already has it.

curl -X GET "${BASE_URL}/roles/permissions-catalog" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Accept: application/json"

Response:

{
  "data": {
    "resources": [
      {
        "resource": "tasks",
        "label": "Tasks",
        "group": "Tools",
        "description": "Create tasks and assign them across the team.",
        "permissions": [
          {
            "scope": "tasks.view",
            "action": "view",
            "name": "View Tasks",
            "description": "View tasks assigned across the team."
          },
          {
            "scope": "tasks.edit",
            "action": "edit",
            "name": "Edit Tasks",
            "description": "Create, assign, and update tasks."
          }
        ]
      }
    ],
    "hierarchy": { "view": 1, "edit": 2, "delete": 3, "manage": 4 },
    "actionImplies": {
      "view": [],
      "edit": ["view"],
      "delete": ["view"],
      "manage": ["view", "edit", "delete"]
    },
    "implies": {
      "organisation.view": ["members.view", "org-structure.view", "roles.view"],
      "organisation.manage": ["members.manage", "org-structure.manage", "roles.manage"]
    }
  },
  "message": "Permission catalog retrieved successfully"
}

data.resources contains one entry per grantable module. Use permissions[].scope as the values in create and permission-update bodies. Unknown scopes return 400 with invalidPermissions.

List roles

GET /roles

System roles (Super Admin, Admin, Member) and custom roles for the token's organisation. Super Admin's permissions array is ["*"].

curl -X GET "${BASE_URL}/roles" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Accept: application/json"

Response:

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Member",
      "description": "Full management of all workspace modules; no organisation administration",
      "isSystemRole": true,
      "key": "member",
      "organizationId": "507f1f77bcf86cd799439020",
      "permissions": ["tasks.manage", "forms.manage"],
      "memberCount": 3,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "message": "Roles retrieved successfully",
  "count": 1
}

Custom roles omit key. createdBy is { "id", "name" } when a creator was stored. aiGuardrail is present only when a guardrail was saved on the role.

Create a role

POST /roles

Field Type Required Description
name string Yes Unique in the organisation, case-insensitive
permissions string[] Yes Scopes from the catalog. Send [] for none
description string No Shown in the roles list
organizationId string Yes Required by validation. The server replaces it with the organisation on the service-actor token

Do not send isSystemRole. The server stores a custom role.

curl -X POST "${BASE_URL}/roles" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance reviewer",
    "description": "Can review tasks and forms",
    "organizationId": "507f1f77bcf86cd799439020",
    "permissions": ["tasks.view", "forms.view"]
  }'

Response 201:

{
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "name": "Finance reviewer",
    "description": "Can review tasks and forms",
    "isSystemRole": false,
    "organizationId": "507f1f77bcf86cd799439020",
    "permissions": ["tasks.view", "forms.view"],
    "memberCount": 0
  },
  "message": "Role created successfully"
}

Errors:

Status Body When
409 { "status": 409, "errors": { "name": "roleAlreadyExists:Finance reviewer" } } Name already used in the organisation
400 { "status": 400, "errors": { "permissions": "invalidPermissions:not.a.scope" } } A scope is not in the catalog. * is accepted by validation and means full access
422 { "status": 422, "errors": { ... } } Missing name, permissions, or organizationId

Get a role

GET /roles/{id}

curl -X GET "${BASE_URL}/roles/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer <service-actor-token>"

Response: { "data": { ...role }, "message": "Role retrieved successfully" }.

Missing role, or a role in another organisation: 404 with errors.role = roleNotFound:{id}.

Update a role

PATCH /roles/{id}

Field Type Required Description
name string No Ignored when omitted. System role names cannot change
description string No
permissions string[] No Replaces the permission list when sent
curl -X PATCH "${BASE_URL}/roles/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Finance review only"
  }'

Response: { "data": { ...role }, "message": "Role updated successfully" }.

Renaming a system role returns 400 with errors.name = cannotModifySystemRoleName. A duplicate name returns 409 roleAlreadyExists.

Replace permissions

PATCH /roles/{id}/permissions

Field Type Required Description
permissions string[] Yes Full replacement list. Scopes must be in the catalog
curl -X PATCH "${BASE_URL}/roles/507f1f77bcf86cd799439012/permissions" \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["tasks.view", "tasks.edit", "forms.view"]
  }'

Response: { "data": { ...role }, "message": "Role permissions updated successfully" }.

Delete a role

DELETE /roles/{id}

Custom roles only. System roles (Super Admin, Admin, Member) return 400 with errors.role = cannotDeleteSystemRole.

curl -X DELETE "${BASE_URL}/roles/507f1f77bcf86cd799439012" \
  -H "Authorization: Bearer <service-actor-token>"

Response:

{ "message": "Role deleted successfully" }

List members of a role

GET /roles/{id}/members

curl -X GET "${BASE_URL}/roles/507f1f77bcf86cd799439011/members" \
  -H "Authorization: Bearer <service-actor-token>"

Response:

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439030",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  ],
  "message": "Role members retrieved successfully",
  "count": 1
}

Examples

Python

import os
import requests

BASE_URL = "https://api.fermi.dev/public/v1/identity"
token = os.environ["FERMI_SERVICE_ACTOR_TOKEN"]
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

catalog = requests.get(f"{BASE_URL}/roles/permissions-catalog", headers=headers)
catalog.raise_for_status()
scopes = [
    item["scope"]
    for resource in catalog.json()["data"]["resources"]
    for item in resource["permissions"]
]

created = requests.post(
    f"{BASE_URL}/roles",
    headers=headers,
    json={
        "name": "Finance reviewer",
        "description": "Can review tasks and forms",
        "organizationId": os.environ["FERMI_ORGANISATION_ID"],
        "permissions": ["tasks.view", "forms.view"],
    },
)
created.raise_for_status()
role_id = created.json()["data"]["id"]

JavaScript

const BASE_URL = "https://api.fermi.dev/public/v1/identity";
const headers = {
  Authorization: `Bearer ${process.env.FERMI_SERVICE_ACTOR_TOKEN}`,
  "Content-Type": "application/json",
};

const catalogResponse = await fetch(`${BASE_URL}/roles/permissions-catalog`, { headers });
if (!catalogResponse.ok) {
  throw new Error(await catalogResponse.text());
}

const createdResponse = await fetch(`${BASE_URL}/roles`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Finance reviewer",
    description: "Can review tasks and forms",
    organizationId: process.env.FERMI_ORGANISATION_ID,
    permissions: ["tasks.view", "forms.view"],
  }),
});
if (!createdResponse.ok) {
  throw new Error(await createdResponse.text());
}
const roleId = (await createdResponse.json()).data.id;

Summary

Method Path Auth
GET /roles/permissions-catalog Service-actor token
GET /roles Service-actor token
POST /roles Service-actor token
GET /roles/{id} Service-actor token
PATCH /roles/{id} Service-actor token
PATCH /roles/{id}/permissions Service-actor token
DELETE /roles/{id} Service-actor token
GET /roles/{id}/members Service-actor token

Next Steps