A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"key": "teacher",
"name": "Professor",
"is_system": true,
"permissions": [
"$team.manage",
"grades:write"
],
"current_version": 123,
"member_count": 123
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "owner_must_manage_the_team",
"message": "the owner role must keep $team.manage: without it no team in this environment would have anybody who can administer it"
}
}Update a customer role
Requires customers:write. The display name and the permission set; the key is absent from the request on purpose — see the create operation.
permissions is a REPLACEMENT of the whole set, which is the only shape that can remove one. Omit the field to leave the set untouched; send [] to strip it. Both halves of a system role are editable: an organization that wants “Administrador” on screen, or an owner that does not manage billing, is asking for something legitimate. The single exception is $team.manage on owner, which is refused with 409 owner_must_manage_the_team — the last-administrator guard runs when a membership moves, so stripping it here would leave every team in the environment with nobody who can administer it and no membership having changed.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"key": "teacher",
"name": "Professor",
"is_system": true,
"permissions": [
"$team.manage",
"grades:write"
],
"current_version": 123,
"member_count": 123
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "owner_must_manage_the_team",
"message": "the owner role must keep $team.manage: without it no team in this environment would have anybody who can administer it"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Path Parameters
The role.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Response
The role.
A role inside a customer, in one environment. permissions mixes the two vocabularies: $… entries are the capabilities UserKit evaluates, everything else is yours and reaches your backend through the contact's JWT.
The stored literal. Immutable.
"teacher"
"Professor"
owner and member, seeded into every environment. Not deletable; name and permissions still editable.
["$team.manage", "grades:write"]
Which version of the permission set is live. An edit bumps it; a restore moves it back.
Memberships holding this role. A role with any cannot be deleted.