Assignable Roles

GET /api/auth/assignable-roles

Returns the roles that the current user can assign to other users, based on the role hierarchy. A user can only assign roles strictly below their own highest role.

Auth: Required — any authenticated user, with the x-tenant-id header of one of their tenants

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <access_token>`
`x-tenant-id`	Yes	Tenant UUID

Example

curl https://api.reten.ai/api/auth/assignable-roles \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await fetch("https://api.reten.ai/api/auth/assignable-roles", {
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.reten.ai/api/auth/assignable-roles",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
)
data = response.json()

Response `200 OK`

Response for a supervisor (level 3):

{
  "assignableRoles": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440000",
      "name": "operator",
      "description": "Field operator with scoped access to assigned activities",
      "permissions": [
        "project:view",
        "activity:view",
        "commerce-lifecycle-snapshot:view",
        "commerce:manage",
        "activity-result:submit",
        "activity-result:edit"
      ],
      "level": 2
    },
    {
      "id": "bb0e8400-e29b-41d4-a716-446655440000",
      "name": "viewer",
      "description": "Read-only access to tenant data",
      "permissions": [
        "project:view",
        "user:view",
        "activity:view",
        "commerce-lifecycle-snapshot:view"
      ],
      "level": 1
    }
  ],
  "currentUserLevel": 3
}

Field	Type	Description
`assignableRoles`	array	Roles below the current user's highest role, sorted by `level` from highest to lowest
`assignableRoles[].name`	string	Role value — the same string sent in `roles` when registering a user or updating their roles
`assignableRoles[].description`	string \| null	Description of the role, in English
`assignableRoles[].permissions`	string[]	Permissions of the role (see Roles & Permissions); the order is not guaranteed
`assignableRoles[].level`	number	Level of the role in the hierarchy
`currentUserLevel`	number	Level of the current user's highest role

Notes

Role hierarchy: super_admin (6) > admin (5) > fde (4) > supervisor (3) > operator (2) > viewer (1). A higher level means more privilege.
super_admin is never returned: no role is above it.

Error Responses

Status	Description
`400`	`x-tenant-id` header missing — `Missing required header: x-tenant-id`
`401`	Missing or invalid access token
`403`	The user does not belong to the tenant — `User does not have access to the requested tenant`