Admin API: Roles
Operations on roles in the Odudu admin API, one section each. Every request carries a bearer token; the index says which audience it needs and how a refusal is shaped.
GET /admin/tenants/{tenant}/roles
Requires the "manage-tenant" capability, or "view-users".
Also readable with view-users, and so with manage-users, whose holder assigns roles and picks them from this list. Nothing else under /roles is.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
Query parameters
| Name | Type | Required | Details |
|---|---|---|---|
cursor | string | no | The next value of the previous page, to continue after it. |
limit | integer | no | How many items to return. A value over 200 is treated as 200; the default is 50. Constraints: at least 1. |
name | string | no | Only roles whose name starts with this. Constraints: at least 1 character. |
client | string | no | Only the roles of one owner: tenant for the tenant’s own roles, or a client’s internal id for the roles scoped to it. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
items | array of object | yes | The entries of this answer. |
items[] | object | yes | |
items[].id | string | yes | The role’s identifier, a UUID. |
items[].name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
items[].description | string or null | yes | What the role is for, or null. |
items[].client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
items[].client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
items[].default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
items[].created_at | string | yes | When the role was created. |
items[].admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
next | string | no | An opaque cursor for the next page; absent on the last page. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
POST /admin/tenants/{tenant}/roles
Requires the "manage-tenant" capability.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
Request body
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
name | string | yes | The role’s name, which a token carries. It cannot be changed afterwards. Constraints: no bidirectional control characters, at least 1 character. |
description | string or null | no | What the role is for. Constraints: no bidirectional control characters, at least 1 character, at most 1000 characters. |
client_id | string | no | The internal identifier of the client to scope the role to; omit it for a tenant role. |
default_for_new_subjects | boolean | no | Give the role to every subject created from now on. |
Responses
201 Created
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The role’s identifier, a UUID. |
name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
description | string or null | yes | What the role is for, or null. |
client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
created_at | string | yes | When the role was created. |
admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
GET /admin/tenants/{tenant}/roles/count
Requires the "manage-tenant" capability.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
Query parameters
| Name | Type | Required | Details |
|---|---|---|---|
name | string | no | Only roles whose name starts with this. Constraints: at least 1 character. |
client | string | no | Only the roles of one owner: tenant for the tenant’s own roles, or a client’s internal id for the roles scoped to it. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
count | integer | yes | How many items match, up to a cap. |
capped | boolean | yes | True when more match than count says, because counting stops at the cap. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
GET /admin/tenants/{tenant}/roles/{id}
Requires the "manage-tenant" capability.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The role’s identifier, a UUID. |
name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
description | string or null | yes | What the role is for, or null. |
client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
created_at | string | yes | When the role was created. |
admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
PATCH /admin/tenants/{tenant}/roles/{id}
Requires the "manage-tenant" capability.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Request body
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
(body) | object | yes | Constraints: other fields accepted. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The role’s identifier, a UUID. |
name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
description | string or null | yes | What the role is for, or null. |
client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
created_at | string | yes | When the role was created. |
admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
DELETE /admin/tenants/{tenant}/roles/{id}
Requires the "manage-tenant" capability.
Refused with 403 when what it removes reaches an admin capability the caller does not hold. Refused with 409 (about:blank#last-administrator) when it would leave no enabled subject holding tenant-admin — manage-tenants in the system tenant.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Responses
204 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
(body) | any | yes |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
GET /admin/tenants/{tenant}/roles/{id}/composites
Requires the "manage-tenant" capability.
The role’s direct children only, not what they in turn include. Unpaged, like GET /groups/:id/roles: the list is one role’s own edges, which an operator edits edge by edge, not a tenant-wide collection.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
items | array of object | yes | Every built-in scope, in the order a new tenant is given them. |
items[] | object | yes | |
items[].id | string | yes | The role’s identifier, a UUID. |
items[].name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
items[].description | string or null | yes | What the role is for, or null. |
items[].client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
items[].client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
items[].default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
items[].created_at | string | yes | When the role was created. |
items[].admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
POST /admin/tenants/{tenant}/roles/{id}/composites
Requires the "manage-tenant" capability.
A role nests at most 200 children; one more is refused with 409. Nests child_role_id under this role. Refused with 403 when the child reaches an admin capability the caller does not hold, or any admin capability at all while a default role or a default group reaches this one; 409 on a cycle, and on a parent belonging to the tenant’s built-in admin client, whose shape provisioning fixes. Answers the composites’ new ETag, the one GET …/composites answers; If-Match is optional, and a stale one is refused with 412.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Request body
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
child_role_id | string | yes | The role to nest in this one. Whoever holds this role then holds it too. |
Responses
204 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
(body) | any | yes |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
DELETE /admin/tenants/{tenant}/roles/{id}/composites/{childId}
Requires the "manage-tenant" capability.
Removes one edge; 404 when there is none. Refused with 409 when the parent belongs to the tenant’s built-in admin client, since every administrator holding it would lose the child. Answers the composites’ new ETag; If-Match is optional, and a stale one is refused with 412. Refused with 403 when what it removes reaches an admin capability the caller does not hold. Refused with 409 (about:blank#last-administrator) when it would leave no enabled subject holding tenant-admin — manage-tenants in the system tenant.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
childId | string | yes | A row id. Constraints: a UUID. |
Responses
204 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
(body) | any | yes |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
PUT /admin/tenants/{tenant}/roles/{id}/default
Requires the "manage-tenant" capability.
At most 200 roles are default at once; one more is refused with 409. Sets whether every subject created afterwards, self-registered ones included, is granted this role. true is refused with 403 when the role reaches any admin capability, whoever the caller is; false is never refused. Answers the role’s ETag; If-Match is optional, and a stale one is refused with 412.
Path parameters
| Name | Type | Required | Details |
|---|---|---|---|
tenant | string | yes | The tenant being administered, addressed by name. |
id | string | yes | A row id. Constraints: a UUID. |
Request body
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
default | boolean | yes | True to give every subject created from now on this group or role, false to stop. Subjects that already exist are not changed. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The role’s identifier, a UUID. |
name | string | yes | The role’s name, which a token carries. Fixed once the role is made. |
description | string or null | yes | What the role is for, or null. |
client_id | string or null | yes | The internal identifier of the client the role is scoped to, or null for a tenant role. |
client_key | string or null | yes | The client_id of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name. |
default_for_new_subjects | boolean | yes | Whether every subject created from now on is given the role. Subjects that already exist are not changed. |
created_at | string | yes | When the role was created. |
admin_reach | array of string | yes | The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them. |
401 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
403 RFC 9457 problem details
Body: application/problem+json, an RFC 9457 problem document described under problem details.
Documentation coverage: 65 of 65 fields described (100%).