Admin API: Groups

Operations on groups 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}/groups

Requires the "manage-tenant" capability, or "view-users".

Also readable with view-users, and so with manage-users, whose holder assigns groups and picks them from this list. Nothing else under /groups 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 groups whose own name starts with this, at any level. Constraints: at least 1 character.
parent	string	no	Only the groups directly under the group with this id, or root for the groups with no parent.

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 group’s identifier, a UUID.
items[].name	string	yes	The group’s own name, unique among the groups beside it. Fixed once the group is made.
items[].description	string or null	yes	What the group is for, or null.
items[].parent_id	string or null	yes	The group this one sits under, or null for a group at the top level.
items[].default_for_new_subjects	boolean	yes	Whether every subject created from now on joins the group, by the admin API, registration and seeding alike. Subjects that already exist are not changed.
items[].path	string	yes	The names from the top of the tree down to this group, such as /eng/platform. The groups claim carries it, and it is recomputed when the group is moved.
items[].created_at	string	yes	When the group was created.
items[].admin_reach	array of string	yes	The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it.
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}/groups

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	Constraints: no bidirectional control characters, at least 1 character.
description	string or null	no	Constraints: no bidirectional control characters, at least 1 character, at most 1000 characters.
parent_id	string or null	no

Responses

201 Created

Body: application/json

Field	Type	Required	Details
id	string	yes	The group’s identifier, a UUID.
name	string	yes	The group’s own name, unique among the groups beside it. Fixed once the group is made.
description	string or null	yes	What the group is for, or null.
parent_id	string or null	yes	The group this one sits under, or null for a group at the top level.
default_for_new_subjects	boolean	yes	Whether every subject created from now on joins the group, by the admin API, registration and seeding alike. Subjects that already exist are not changed.
path	string	yes	The names from the top of the tree down to this group, such as /eng/platform. The groups claim carries it, and it is recomputed when the group is moved.
created_at	string	yes	When the group was created.
admin_reach	array of string	yes	The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it.

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}/groups/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 groups whose own name starts with this, at any level. Constraints: at least 1 character.
parent	string	no	Only the groups directly under the group with this id, or root for the groups with no parent.

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}/groups/{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 group’s identifier, a UUID.
name	string	yes	The group’s own name, unique among the groups beside it. Fixed once the group is made.
description	string or null	yes	What the group is for, or null.
parent_id	string or null	yes	The group this one sits under, or null for a group at the top level.
default_for_new_subjects	boolean	yes	Whether every subject created from now on joins the group, by the admin API, registration and seeding alike. Subjects that already exist are not changed.
path	string	yes	The names from the top of the tree down to this group, such as /eng/platform. The groups claim carries it, and it is recomputed when the group is moved.
created_at	string	yes	When the group was created.
admin_reach	array of string	yes	The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it.

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}/groups/{id}

Requires the "manage-tenant" capability.

Amends description (at most 1000 characters, null to clear) and reparents the group. A reparent is refused with 403 when the new parent’s chain, or the old one it leaves, 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.

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 group’s identifier, a UUID.
name	string	yes	The group’s own name, unique among the groups beside it. Fixed once the group is made.
description	string or null	yes	What the group is for, or null.
parent_id	string or null	yes	The group this one sits under, or null for a group at the top level.
default_for_new_subjects	boolean	yes	Whether every subject created from now on joins the group, by the admin API, registration and seeding alike. Subjects that already exist are not changed.
path	string	yes	The names from the top of the tree down to this group, such as /eng/platform. The groups claim carries it, and it is recomputed when the group is moved.
created_at	string	yes	When the group was created.
admin_reach	array of string	yes	The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it.

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}/groups/{id}

Requires the "manage-tenant" capability.

Deletes the group and its whole subtree. 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}/groups/{id}/roles

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
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.
items[].name	string	yes	The role name.
items[].client_id	string or null	yes	For a role scoped to a client, that client’s internal id; null for a tenant-wide role.
items[].client_key	string or null	yes	For a client role, the client’s client_id.
items[].admin_reach	array of string	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}/groups/{id}/roles

Requires the "manage-tenant" capability.

More than 200 entries is refused with 400. Replaces the whole list. If-Match is mandatory: the matching GET answers an ETag, an absent header is refused with 428, and a stale one with 412 — a last-write-wins here would silently reinstate what another administrator has just removed. Refused with 403 when a role it adds or leaves out reaches an admin capability the caller does not hold; a role it keeps is not counted. 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.

Request body

Body: application/json

Field	Type	Required	Details
role_ids	array of string	yes	The identifiers of every role the subject should hold. Replaces the current set. Constraints: at most 200 items.

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.
items[].name	string	yes	The role name.
items[].client_id	string or null	yes	For a role scoped to a client, that client’s internal id; null for a tenant-wide role.
items[].client_key	string or null	yes	For a client role, the client’s client_id.
items[].admin_reach	array of string	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}/groups/{id}/default

Requires the "manage-tenant" capability.

At most 200 groups are default at once; one more is refused with 409. Sets whether every subject created afterwards — by an administrator, by self-registration or by odudu seed — joins this group; an imported subject keeps the memberships its document lists. true is refused with 403 when the group’s roles, or any ancestor’s, reach an admin capability, whoever the caller is; false is never refused. While a group is a default, mapping a role that reaches a capability to it or to an ancestor, nesting one under a role it reaches, and moving it or an ancestor under a chain that reaches one are refused the same way. Answers the group’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 group’s identifier, a UUID.
name	string	yes	The group’s own name, unique among the groups beside it. Fixed once the group is made.
description	string or null	yes	What the group is for, or null.
parent_id	string or null	yes	The group this one sits under, or null for a group at the top level.
default_for_new_subjects	boolean	yes	Whether every subject created from now on joins the group, by the admin API, registration and seeding alike. Subjects that already exist are not changed.
path	string	yes	The names from the top of the tree down to this group, such as /eng/platform. The groups claim carries it, and it is recomputed when the group is moved.
created_at	string	yes	When the group was created.
admin_reach	array of string	yes	The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it.

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: 62 of 67 fields described (92%).