Permission Groups

GET /api/auth/permission-groups

Returns all available permissions grouped by functional area. Useful for building permission assignment UIs.

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/permission-groups \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await fetch("https://api.reten.ai/api/auth/permission-groups", {
  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/permission-groups",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
)
data = response.json()

Response `200 OK`

Excerpt — the response has 16 groups, and every permission appears in exactly one of them:

{
  "groups": [
    {
      "name": "User Management",
      "permissions": [
        { "key": "user:create", "description": "Create new users" },
        { "key": "user:view", "description": "View user list and details" },
        { "key": "user:update", "description": "Update user information" },
        { "key": "user:delete", "description": "Delete users" },
        { "key": "user:reset-password", "description": "Reset other users passwords" }
      ]
    },
    {
      "name": "Projects",
      "permissions": [
        { "key": "project:create", "description": "Create new projects within the tenant" },
        { "key": "project:view", "description": "View the project list of the tenant" },
        { "key": "project:update", "description": "Rename projects and edit their root audience" }
      ]
    },
    {
      "name": "Activities",
      "permissions": [
        { "key": "activity:view", "description": "View activity list and details" },
        { "key": "activity:create", "description": "Create new activities" },
        { "key": "activity:cancel", "description": "Cancel activities in READY status" },
        { "key": "activity-config:manage", "description": "Manage activity configuration (target resolution)" },
        { "key": "activity:dispatch", "description": "Manually dispatch activities to external providers" },
        { "key": "activity:force-retry-dispatch", "description": "Force retry dispatch for failed activities" }
      ]
    }
  ]
}

Response Shape

Field	Type	Description
`groups`	array	List of permission groups, always in the same order
`groups[].name`	string	Group display name, in English
`groups[].permissions`	array	Permissions in this group
`groups[].permissions[].key`	string	Permission value — the same string sent in the `permissions` of `POST /api/api-keys`
`groups[].permissions[].description`	string	Human-readable description, in English

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`