Public reference

Roles

Every endpoint in this group. Open one for its parameters and a worked example.

7 Endpoints

Roles

GET /api/v1/roles List roles prm_roles_manage

Every role visible to the tenant, with its permission count and the exact code set it grants. System roles sort first.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions

Un-paginated. template_key is the provisioning slug a seeded role came from, and is null for a hand-made one — it is populated by this list only, not by the role pickers.

Open the full reference

Response 200 OK

{
  "data": [
    {
      "id": 2,
      "tenant_id": 12,
      "name": "support",
      "description": "Read subscribers, reply to tickets",
      "is_system": false,
      "template_key": "support",
      "immutable": false,
      "permission_count": 14,
      "permissions": ["prm_tickets_reply", "prm_tickets_view", "prm_users_index"]
    }
  ]
}

POST /api/v1/roles Create a role prm_roles_manage

Creates a named permission set. A caller may only grant codes they hold themselves, so a role cannot be used to mint authority its author does not have.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions
Rate limit: t_mutate

The containment rule is the point of this endpoint. You cannot author a role carrying a permission you lack, and you cannot assign someone else's role that carries one either — the assign path runs the same check, because otherwise the author check would be trivially bypassed.

Parameters

Parameter	Description
`name`required body · string	Unique within the tenant. Reserved names are refused.
`permissions` body · array	Permission codes from the catalogue. Unknown codes are rejected, not dropped.

Open the full reference

POST /api/v1/roles/bulk-delete Manage roles & permissions prm_roles_manage

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

DELETE /api/v1/roles/{id} Delete a role prm_roles_manage

Removes the role. System and immutable roles are refused, and so is a role that is still assigned.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions
Rate limit: t_mutate

Parameters

Parameter	Description
`id`required path · integer	Role id.

Open the full reference

GET /api/v1/roles/{id} Fetch one role prm_roles_manage

The role and the exact set of permission codes it grants.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions

Parameters

Parameter	Description
`id`required path · integer	Role id.

Open the full reference

PATCH /api/v1/roles/{id} Update a role prm_roles_manage

Edits the name, description and permission set. The immutable administrator role cannot be edited at all.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions
Rate limit: t_mutate

Changing a role changes the authority of every manager holding it, and every API token those managers own, on the next request. There is no notification and no record against the affected tokens.

Parameters

Parameter	Description
`id`required path · integer	Role id.

Open the full reference

PUT /api/v1/roles/{id}/portal-permissions Set a role's subscriber-portal permissions prm_roles_manage

The separate set that governs what a SUBSCRIBER may do in the self-service portal, not what a manager may do in the admin API. Different catalogue, different meaning.

Authentication: Staff token or session
Requires permission: prm_roles_manage Manage roles & permissions
Rate limit: t_mutate

These are not prm_* codes and they do not affect the admin API at all. Confusing the two sets is the usual cause of "I gave the role the permission and nothing changed".

Parameters

Parameter	Description
`id`required path · integer	Role id.

Open the full reference

Written to be read by machines too

The reference is public and needs no account, so a tool that has never seen X-Radius can reach a correct first call on its own.

/llms.txt: An index of every page, with one-line summaries.
/llms-full.txt: The whole reference as one Markdown file, with no navigation to crawl.
/openapi.json: OpenAPI 3.1, generated from the router that serves this instance.
/skill.md: A ready-made skill file for an assistant: authentication, the response envelope and the error codes in one page.
<page-url>.md: Append .md to any reference URL for the same page as Markdown.
Accept: text/markdown: Send this header on the ordinary URL and the answer comes back as Markdown instead.

Hand this to your assistant

Read https://x-radius.com/llms.txt, then fetch the endpoint you need as Markdown by appending .md to its URL.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us