Create a role

POST /api/v1/roles 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.

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.

At a glance

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

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.

Errors

Code	When it is returned
`ERR_VALIDATION`400	an unknown permission code, or a reserved role name
`ERR_FORBIDDEN`403	the role would grant a permission the caller does not hold
`ERR_VALIDATION`409	the role name already exists in this tenant

Request

curl -X POST "$BASE/api/v1/roles" \
  -H "Authorization: Bearer $XR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "front-desk",
  "description": "Sell cards, read subscribers",
  "permissions": ["prm_users_index", "prm_cards_verify", "prm_pos_sell"]
}'

BASE is your tenant host: the same address you sign in on.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us