Admin API: Subjects

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

Requires the "view-users" capability.

The subjects of a tenant, paged. capability narrows to the holders of one admin capability, of tenant-admin, or of any, held effectively; with it, each item carries admin_capabilities, every name it holds and whether one is assigned to it directly.

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.
username	string	no	Only subjects whose username starts with this, ignoring case. Constraints: at least 1 character.
email	string	no	Only subjects whose email starts with this, ignoring case. Constraints: at least 1 character.
name	string	no	Only subjects whose full name starts with this, ignoring case. Constraints: at least 1 character.
given_name	string	no	Only subjects whose first name starts with this, ignoring case. Constraints: at least 1 character.
family_name	string	no	Only subjects whose last name starts with this, ignoring case. Constraints: at least 1 character.
enabled	string	no	true for enabled subjects only, false for disabled ones only. Constraints: one of true, false.
role	string	no	Only subjects holding this role, by role id. Constraints: a UUID.
group	string	no	Only members of this group, by group id. Constraints: a UUID.
capability	string	no	Only holders of this admin capability, tenant-admin, or any admin capability; held effectively. Constraints: one of view-users, manage-users, manage-clients, manage-tenant, manage-keys, manage-sessions, view-audit, manage-tenants, tenant-admin, any.
type	string	no	Only subjects of this type. Constraints: one of user, service, agent_instance.
locked	string	no	true for subjects locked out by failed sign-ins only. Constraints: one of true, false.

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 subject’s identifier, a UUID.
items[].type	string	yes	user is a person, service is the account of a confidential client, agent_instance is an automated agent. Constraints: one of user, service, agent_instance.
items[].username	string or null	yes	The name the subject signs in with, or null for a subject that does not.
items[].email	string or null	yes	The subject’s email address, or null.
items[].enabled	boolean	yes	A disabled subject cannot sign in or get tokens.
items[].created_at	string	yes	When the subject was created.
items[].admin_capabilities	array of object	no	Present when the list was filtered by capability: every admin capability the subject holds.
items[].admin_capabilities[]	object	yes
items[].admin_capabilities[].name	string	yes	The admin capability, or tenant-admin, which holds them all. Constraints: one of view-users, manage-users, manage-clients, manage-tenant, manage-keys, manage-sessions, view-audit, manage-tenants, tenant-admin.
items[].admin_capabilities[].direct	boolean	yes	True when it is assigned to the subject itself, false when it comes through a group or a role.
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}/subjects

Requires the "manage-users" 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
username	string	yes	The sign-in name. Unique in the tenant, case counts. Constraints: no bidirectional control characters, at least 1 character.
email	string	no	The email address, if any. Constraints: at least 1 character.

{
  "username": "ada",
  "email": "ada@example.com"
}

Responses

201 Created

Body: application/json

Field	Type	Required	Details
id	string	yes	The subject’s identifier, a UUID.
type	string	yes	user is a person, service is the account of a confidential client, agent_instance is an automated agent. Constraints: one of user, service, agent_instance.
username	string or null	yes	The name the subject signs in with, or null for a subject that does not.
email	string or null	yes	The subject’s email address, or null.
enabled	boolean	yes	A disabled subject cannot sign in or get tokens.
created_at	string	yes	When the subject was created.

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}/subjects/count

Requires the "view-users" capability.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Query parameters

Name	Type	Required	Details
username	string	no	Only subjects whose username starts with this, ignoring case. Constraints: at least 1 character.
email	string	no	Only subjects whose email starts with this, ignoring case. Constraints: at least 1 character.
name	string	no	Only subjects whose full name starts with this, ignoring case. Constraints: at least 1 character.
given_name	string	no	Only subjects whose first name starts with this, ignoring case. Constraints: at least 1 character.
family_name	string	no	Only subjects whose last name starts with this, ignoring case. Constraints: at least 1 character.
enabled	string	no	true for enabled subjects only, false for disabled ones only. Constraints: one of true, false.
role	string	no	Only subjects holding this role, by role id. Constraints: a UUID.
group	string	no	Only members of this group, by group id. Constraints: a UUID.
capability	string	no	Only holders of this admin capability, tenant-admin, or any admin capability; held effectively. Constraints: one of view-users, manage-users, manage-clients, manage-tenant, manage-keys, manage-sessions, view-audit, manage-tenants, tenant-admin, any.
type	string	no	Only subjects of this type. Constraints: one of user, service, agent_instance.
locked	string	no	true for subjects locked out by failed sign-ins only. Constraints: one of true, false.

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}/subjects/username-policy

Requires the "view-users" capability.

Whether this tenant accepts a rename: its username_editable setting, readable by whoever can read subjects, where GET /admin/tenants/{tenant}/settings needs manage-tenant. No ETag: nothing is written against it.

Path parameters

Name	Type	Required	Details
tenant	string	yes	The tenant being administered, addressed by name.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
username_editable	boolean	yes	Whether the tenant lets a username be changed.

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}/subjects/bulk

Requires the "manage-users" capability.

Applies one action to at most 100 subjects, each exactly as its single-subject door would — PATCH …/subjects/{id} for disable and enable, DELETE …/subjects/{id}, and DELETE …/subjects/{id}/sessions for end-sessions, which additionally requires manage-sessions — each in its own transaction with its own audit row. Answers 200 with the status each id would have had, and a refusal’s problem type and detail. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling). 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.

Request body

Body: application/json

Field	Type	Required	Details
action	string	yes	What to do to every listed subject: disable, enable, delete or end-sessions. Constraints: one of disable, enable, delete, end-sessions.
ids	array of string	yes	The subjects to act on, at most 100. Constraints: at least 1 item, at most 100 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 subject.
items[].status	integer	yes	The HTTP status this subject’s part of the call would have had alone.
items[].type	string	no	The problem type when it was refused.
items[].detail	string	no	Why it was refused.
items[].ended	integer	no	For end-sessions, how many sessions were ended. Constraints: at least 0.

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

Requires the "view-users" 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 subject’s identifier, a UUID.
type	string	yes	user is a person, service is the account of a confidential client, agent_instance is an automated agent. Constraints: one of user, service, agent_instance.
username	string or null	yes	The name the subject signs in with, or null for a subject that does not.
email	string or null	yes	The subject’s email address, or null.
enabled	boolean	yes	A disabled subject cannot sign in or get tokens.
created_at	string	yes	When the subject was created.

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

Requires the "manage-users" capability.

Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling). 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
username	string	no	A new sign-in name, when the tenant allows renaming. Constraints: at least 1 character.
email	string or null	no	A new email address, or null to remove it. Constraints: at least 1 character.
enabled	boolean	no	Whether the subject may sign in.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
id	string	yes	The subject’s identifier, a UUID.
type	string	yes	user is a person, service is the account of a confidential client, agent_instance is an automated agent. Constraints: one of user, service, agent_instance.
username	string or null	yes	The name the subject signs in with, or null for a subject that does not.
email	string or null	yes	The subject’s email address, or null.
enabled	boolean	yes	A disabled subject cannot sign in or get tokens.
created_at	string	yes	When the subject was created.

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

Requires the "manage-users" capability.

Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling). Refused with 409 (about:blank#last-administrator) when it would leave no enabled subject holding tenant-admin — manage-tenants in the system tenant. Refused with 409 (about:blank#service-account) for the service account of a client; delete the client instead.

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

Requires the "view-users" 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
name	string or null	yes	The user’s full name, as they would write it.
given_name	string or null	yes	The first name.
family_name	string or null	yes	The last name.
middle_name	string or null	yes	The middle name.
nickname	string or null	yes	A casual name.
preferred_username	string or null	yes	The name the user prefers to be addressed by; separate from the sign-in username.
profile	string or null	yes	The address of the user’s profile page.
picture	string or null	yes	The address of the user’s picture.
website	string or null	yes	The address of the user’s web page.
gender	string or null	yes	The user’s gender, in the user’s own words.
birthdate	string or null	yes	The birth date as YYYY-MM-DD, or YYYY alone.
zoneinfo	string or null	yes	The time zone as an IANA name, such as Europe/Berlin.
locale	string or null	yes	The preferred language as a BCP 47 tag, such as en-GB.
phone_number	string or null	yes	The telephone number, ideally in E.164 form.
phone_number_verified	boolean	yes	Whether the phone number was verified.
email_verified	boolean	yes	Whether the email address was verified.
address_formatted	string or null	yes	The whole postal address as one multi-line string.
address_street	string or null	yes	The street address.
address_locality	string or null	yes	The city or locality.
address_region	string or null	yes	The state, province or region.
address_postal_code	string or null	yes	The postal code.
address_country	string or null	yes	The country.
profile_updated_at	string or null	yes	When the profile last changed, or null.

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

Requires the "manage-users" capability.

Amends the OIDC claim columns a subject carries — every profileSchema member except profile_updated_at, which the write stamps itself. email and username are refused here, naming PATCH /admin/tenants/{tenant}/subjects/{id}, which owns each. Submitting a different phone_number without also setting phone_number_verified in the same request resets it to false — a different number is not a verified one, the way amending email through the subjects route resets email_verified; resubmitting the same number leaves it untouched. If-Match is optional: honoured when present, never required. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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
name	string or null	no	The user’s full name, as they would write it.
given_name	string or null	no	The first name.
family_name	string or null	no	The last name.
middle_name	string or null	no	The middle name.
nickname	string or null	no	A casual name.
preferred_username	string or null	no	The name the user prefers to be addressed by; separate from the sign-in username.
profile	string or null	no	The address of the user’s profile page.
picture	string or null	no	The address of the user’s picture.
website	string or null	no	The address of the user’s web page.
gender	string or null	no	The user’s gender, in the user’s own words.
birthdate	string or null	no	The birth date as YYYY-MM-DD, or YYYY alone.
zoneinfo	string or null	no	The time zone as an IANA name, such as Europe/Berlin.
locale	string or null	no	The preferred language as a BCP 47 tag, such as en-GB.
phone_number	string or null	no	The telephone number, ideally in E.164 form.
phone_number_verified	boolean	no	Whether the phone number was verified.
email_verified	boolean	no	Whether the email address was verified.
address_formatted	string or null	no	The whole postal address as one multi-line string.
address_street	string or null	no	The street address.
address_locality	string or null	no	The city or locality.
address_region	string or null	no	The state, province or region.
address_postal_code	string or null	no	The postal code.
address_country	string or null	no	The country.
email	any	no	Refused here: change the email address with the subject’s own email.
username	any	no	Refused here: change the username with the subject’s own username.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
name	string or null	yes	The user’s full name, as they would write it.
given_name	string or null	yes	The first name.
family_name	string or null	yes	The last name.
middle_name	string or null	yes	The middle name.
nickname	string or null	yes	A casual name.
preferred_username	string or null	yes	The name the user prefers to be addressed by; separate from the sign-in username.
profile	string or null	yes	The address of the user’s profile page.
picture	string or null	yes	The address of the user’s picture.
website	string or null	yes	The address of the user’s web page.
gender	string or null	yes	The user’s gender, in the user’s own words.
birthdate	string or null	yes	The birth date as YYYY-MM-DD, or YYYY alone.
zoneinfo	string or null	yes	The time zone as an IANA name, such as Europe/Berlin.
locale	string or null	yes	The preferred language as a BCP 47 tag, such as en-GB.
phone_number	string or null	yes	The telephone number, ideally in E.164 form.
phone_number_verified	boolean	yes	Whether the phone number was verified.
email_verified	boolean	yes	Whether the email address was verified.
address_formatted	string or null	yes	The whole postal address as one multi-line string.
address_street	string or null	yes	The street address.
address_locality	string or null	yes	The city or locality.
address_region	string or null	yes	The state, province or region.
address_postal_code	string or null	yes	The postal code.
address_country	string or null	yes	The country.
profile_updated_at	string or null	yes	When the profile last changed, or null.

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

Requires the "view-users" 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	no	The credential’s identifier, for deleting it. Absent for a password.
items[].type	string	yes	password, totp (an authenticator app), webauthn (a passkey) or recovery-code. Constraints: one of password, totp, webauthn, recovery-code.
items[].created_at	string	yes	When the credential was set up.
items[].expired	boolean	no	For a password, whether the tenant’s maximum password age has passed.
items[].recovery_code_count	integer	no	For recovery codes, how many unused codes remain.

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}/subjects/{id}/credentials/{credentialId}

Requires the "manage-users" capability.

Removes one credential; a password is refused with 409. When the credential is the TOTP the subject holds, their whole set of recovery codes is revoked with it, and an owed set is dropped, since a code only stands in for a TOTP code (a passkey is not one); a later enrolment issues a fresh set. The subject is told by mail at their address on file, verified or not, if they have one. With end_sessions=true every live session of the subject ends in the same transaction, as DELETE …/sessions ends them, and also needs manage-sessions; the removal and the ending succeed or fail together. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.
credentialId	string	yes	A row id. Constraints: a UUID.

Query parameters

Name	Type	Required	Details
end_sessions	string	no	true also ends every live session of the subject in the same transaction as the removal, queueing their back-channel logouts as DELETE …/sessions does; the default false leaves them signed in. Constraints: one of true, false.

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

Requires the "view-users" capability.

The subject’s consents, paged by keyset on the client’s own client_id: limit up to 200, and next (also the link header) names the following page; a response with no next is the last.

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.

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.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
items	array of object	yes	The entries of this answer.
items[]	object	yes
items[].client_id	string	yes	The client’s internal identifier.
items[].client_key	string	yes	The client’s client_id.
items[].scope_names	array of string	yes	The scopes the user agreed to.
items[].granted_at	string	yes	When the user agreed.
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.

DELETE /admin/tenants/{tenant}/subjects/{id}/consents/{clientId}

Requires the "manage-users" capability.

Withdraws the grant so the next /authorize for this client asks again, and revokes every token issued under it — a subject who revokes access is not still impersonated by a refresh token that outlives the consent it was granted under. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.
clientId	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.

POST /admin/tenants/{tenant}/subjects/{id}/password

Requires the "manage-users" capability.

Replaces the subject’s password with a server-generated one-time password, answered once in this body and never again, and owes update-password so the subject changes it at the next sign-in. Ends no session and revokes no grant, as a password reset does not; DELETE /admin/tenants/{tenant}/subjects/{id}/sessions is that door. A subject with no users row answers 404. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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

201 Created

Body: application/json

Field	Type	Required	Details
password	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.

POST /admin/tenants/{tenant}/subjects/{id}/password-reset

Requires the "manage-users" capability.

Queues the reset-password link a self-service request sends, to the subject’s own address. The link is never in this response or the audit trail. 409 with its own problem type when the subject has no email (no-email), when the tenant’s reset_password_allowed is off so the link would be refused (reset-password-off), or when its mail would only be logged, GET …/smtp’s none (no-mail-relay). Rate-limited per origin, as the self-service request is. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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

202 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.

POST /admin/tenants/{tenant}/subjects/{id}/verification

Requires the "manage-users" capability.

Queues a fresh email-verification link to the subject’s own address. The link is never in this response or the audit trail. 409 no-email or no-mail-relay as POST …/password-reset answers them. Rate-limited per origin. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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

202 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.

POST /admin/tenants/{tenant}/subjects/{id}/actions-email

Requires the "manage-users" capability.

Queues a link to the subject’s own address that takes them through actions, a non-empty subset of the required actions PUT …/required-actions takes. Following it sets a new password where update-password is named, and owes the rest, so the next sign-in asks for each; the link alone never enrols a factor. The link is never in this response or the audit trail. The same 409s as POST …/password-reset, reset-password-off only when update-password is named. Rate-limited per origin. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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
actions	array of string	yes	The required actions after the change. Constraints: at least 1 item.

Responses

202 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}/subjects/{id}/lockout

Requires the "view-users" capability.

The subject’s run of failed sign-ins: how many, the last one, and whether the account is locked now, judged by the server’s clock. A subject that has never failed answers a zero count. 404 for a subject with no users row.

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
locked	boolean	yes
locked_until	string or null	yes
failure_count	integer	yes
last_failure_at	string or null	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}/subjects/{id}/lockout

Requires the "manage-users" capability.

Clears the subject’s brute-force failure count, and with it any lockout, so the next correct password signs in. 204 whether or not anything was recorded; 404 for a subject with no users row, which has no sign-in to be locked out of. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.

DELETE /admin/tenants/{tenant}/subjects/{id}/recovery-codes

Requires the "manage-users" capability.

Revokes every recovery code the subject holds, spent or not, so none signs in again. Recovery codes carry no id of their own, so this is the only way to remove them. 204 whether or not any were held; 404 for a subject with no users row. While the subject still holds a TOTP, the generate-recovery-codes required action is added so their next sign-in asks for a fresh set, unless require_new_set is false; with no TOTP left a set would serve nothing, and none is asked for. The subject is told by mail at their address on file, if they have one. Removing the last TOTP through DELETE …/credentials/{credentialId} revokes the set the same way, without being asked. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.

Query parameters

Name	Type	Required	Details
require_new_set	string	no	true (the default) owes the subject a new set of recovery codes at their next sign-in when a second factor remains; false leaves them with none until one is asked of them. Constraints: one of true, false.

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}/subjects/{id}/required-actions

Requires the "view-users" 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
actions	array of string	yes	The required actions after the change.

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}/subjects/{id}/required-actions

Requires the "manage-users" capability.

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 the subject holds an admin capability the caller does not (the target ceiling).

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
actions	array of string	yes	The required actions after the change.

{
  "actions": [
    "update-password",
    "configure-totp"
  ]
}

Responses

200 OK

Body: application/json

Field	Type	Required	Details
actions	array of string	yes	The required actions after the change.

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

Requires the "view-users" 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.

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

Requires the "manage-users" 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 the subject holds an admin capability the caller does not (the target ceiling). 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.

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}/subjects/{id}/effective-roles

Requires the "view-users" capability.

A page holds at most limit roles (up to 200); follow next (or the link header) until it is absent for the whole set. The roles the subject holds, the set token issuance and authorization read, in id order, each with every path it is held by: assigned directly, mapped to a group the subject belongs to or to one of its ancestors, or nested under another role it holds. Paged, and carrying no ETag: GET …/roles is the list PUT …/roles replaces.

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.

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.

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.
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[].via	array of any	yes	How the subject holds the role: directly, through a group, or through a composite role.
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.

GET /admin/tenants/{tenant}/subjects/{id}/admin-capabilities

Requires the "view-users" capability.

The admin capabilities the subject holds, each as an effective role with every path it is held by, and the roles that carry them (one nesting a capability, held directly or through a group), found among the roles that reach a capability whatever else the subject holds. Never a page: at most 200 carriers, and complete is false when more exist, in which case nothing may be judged from it. What a console judges the subject’s reach, and what losing a role would take, by.

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	The roles that carry admin capabilities, with how the subject holds each.
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[].via	array of any	yes	How the subject holds the role: directly, through a group, or through a composite role.
complete	boolean	yes	False when the list was cut at its bound.

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

Requires the "view-users" 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 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.

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

Requires the "manage-users" capability.

More than 200 entries is refused with 400. Replaces the subject’s direct memberships. If-Match is mandatory (428 absent, 412 stale). Refused with 403 when the groups, their ancestors or the composites their roles nest reach an admin capability the caller does not hold. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling). 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
group_ids	array of string	yes	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 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.

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

Requires the "manage-sessions" 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.

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.

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 session’s identifier.
items[].created_at	string	yes	When the user signed in.
items[].last_active_at	string	yes	When the session last did anything.
items[].remembered	boolean	yes	Whether the user chose to stay signed in, which gives the session the longer remember-me lifetimes.
items[].client_ids	array of string	yes	The clients the session has signed the user in to.
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.

DELETE /admin/tenants/{tenant}/subjects/{id}/sessions

Requires the "manage-sessions" capability.

Ends every live session the subject holds, each exactly as DELETE /admin/tenants/{tenant}/subjects/{id}/sessions/{sid} ends one: its grants revoked and a Back-Channel Logout Token delivered to every registered client that used it. Answers how many were ended. A grant bound to no session — offline_access — is left alone, as it is by ending one. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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
ended	integer	yes	How many sessions were ended. Constraints: at least 0.

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}/subjects/{id}/sessions/{sid}

Requires the "manage-sessions" capability.

Ends the session and delivers a Back-Channel Logout Token to every registered client that used it. No Front-Channel Logout is attempted: there is no browser here to render its iframes in. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.
sid	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}/subjects/{id}/grants

Requires the "manage-sessions" capability.

Every grant the subject holds that nothing has revoked, session-bound or not: offline is true for a grant whose scope carries offline_access, which ending sessions leaves alone; a client_credentials grant has no session and is not offline. Never a token.

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.

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.

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 grant’s identifier.
items[].client_id	string	yes	The client the grant was issued to, by its internal id.
items[].client_key	string	yes	That client’s client_id.
items[].scope	string	yes	The scopes the grant covers, space-separated.
items[].created_at	string	yes	When the user authorized it.
items[].session_id	string or null	yes	The session it is tied to, or null for an offline grant.
items[].offline	boolean	yes	True when the grant outlives the user’s session (the offline_access scope).
items[].refresh_expires_at	string or null	yes	When its refresh token expires, or null.
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.

DELETE /admin/tenants/{tenant}/subjects/{id}/grants/{clientId}

Requires the "manage-sessions" capability.

Revokes every grant the subject holds through the client, offline ones included, so no refresh token issued under them is honoured again. Withdraws no consent and ends no session. Answers how many were revoked. Refused with 403 when the subject holds an admin capability the caller does not (the target ceiling).

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.
clientId	string	yes	A row id. Constraints: a UUID.

Responses

200 OK

Body: application/json

Field	Type	Required	Details
revoked	integer	yes	How many grants were revoked. Constraints: at least 0.

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: 225 of 231 fields described (97%).