RBAC¶
Manage roles and the permission catalog for an organisation.
Base URL¶
Authentication¶
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:
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:
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 |