Admin API: Scopes
Operations on scopes 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}/scopes
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 |
|---|---|---|---|
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 | Constraints: at least 1 character. |
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 scope’s identifier. |
items[].name | string | yes | The scope name clients request, such as profile. |
items[].description | string or null | yes | Free text for administrators, or null. |
items[].include_in_id_token | boolean | yes | Whether the claims this scope adds appear in the ID token. |
items[].include_in_access_token | boolean | yes | Whether the claims this scope adds appear in the access token. |
items[].default_client_assignment | string or null | yes | How every new client gets this scope: default, optional, or null for neither. Constraints: one of default, optional. |
items[].consent_text | string or null | yes | The sentence the consent screen shows for this scope, or null to use its name. |
items[].display_order | integer | yes | Where the scope sorts on the consent screen; lowest first. |
items[].created_at | string | yes | When the scope was created. |
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}/scopes
Requires the "manage-tenant" capability.
A tenant defines at most 1,000 scopes; one more is refused with 409. At most 200 scopes are marked (default_client_assignment) for every new client; marking another is refused with 409.
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 scope name clients will request. Unique in the tenant. Constraints: at least 1 character. |
description | string or null | no | Free text for administrators. Constraints: no bidirectional control characters, at least 1 character. |
include_in_id_token | boolean | no | Whether its claims appear in the ID token. |
include_in_access_token | boolean | no | Whether its claims appear in the access token. |
default_client_assignment | string or null | no | Assign it to every new client as default or optional. Constraints: one of default, optional. |
consent_text | string or null | no | The sentence the consent screen shows for it. Constraints: no bidirectional control characters, at least 1 character, at most 500 characters. |
display_order | integer | no | Where it sorts on the consent screen; lowest first. Constraints: at least 0, at most 2147483647. |
Responses
201 Created
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The scope’s identifier. |
name | string | yes | The scope name clients request, such as profile. |
description | string or null | yes | Free text for administrators, or null. |
include_in_id_token | boolean | yes | Whether the claims this scope adds appear in the ID token. |
include_in_access_token | boolean | yes | Whether the claims this scope adds appear in the access token. |
default_client_assignment | string or null | yes | How every new client gets this scope: default, optional, or null for neither. Constraints: one of default, optional. |
consent_text | string or null | yes | The sentence the consent screen shows for this scope, or null to use its name. |
display_order | integer | yes | Where the scope sorts on the consent screen; lowest first. |
created_at | string | yes | When the scope 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}/scopes/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 | Constraints: at least 1 character. |
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}/scopes/{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 scope’s identifier. |
name | string | yes | The scope name clients request, such as profile. |
description | string or null | yes | Free text for administrators, or null. |
include_in_id_token | boolean | yes | Whether the claims this scope adds appear in the ID token. |
include_in_access_token | boolean | yes | Whether the claims this scope adds appear in the access token. |
default_client_assignment | string or null | yes | How every new client gets this scope: default, optional, or null for neither. Constraints: one of default, optional. |
consent_text | string or null | yes | The sentence the consent screen shows for this scope, or null to use its name. |
display_order | integer | yes | Where the scope sorts on the consent screen; lowest first. |
created_at | string | yes | When the scope 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}/scopes/{id}
Requires the "manage-tenant" capability.
Marking a scope for every new client (default_client_assignment) is refused with 409 once 200 are marked.
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 scope’s identifier. |
name | string | yes | The scope name clients request, such as profile. |
description | string or null | yes | Free text for administrators, or null. |
include_in_id_token | boolean | yes | Whether the claims this scope adds appear in the ID token. |
include_in_access_token | boolean | yes | Whether the claims this scope adds appear in the access token. |
default_client_assignment | string or null | yes | How every new client gets this scope: default, optional, or null for neither. Constraints: one of default, optional. |
consent_text | string or null | yes | The sentence the consent screen shows for this scope, or null to use its name. |
display_order | integer | yes | Where the scope sorts on the consent screen; lowest first. |
created_at | string | yes | When the scope 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}/scopes/{id}
Requires the "manage-tenant" capability.
Cascades to every client’s assignment and role mapping naming the scope; GET …/impact counts them first. A built-in scope — one every tenant is given, decided by its name alone — is deleted only when confirm names it again, refused with 422 builtin-scope-confirmation otherwise, the detail naming the scope and what would go with it; POST …/scopes/restore-builtins creates it again, without what the cascade took. Refused with 409 for the scope named openid, which every client’s assignment of it — the tenant’s built-in admin client included — would otherwise be stripped of in the same stroke, whatever confirm says. The audit row carries builtin and both counts. Refused with 403 when what it removes reaches an admin capability the caller does not hold.
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 |
|---|---|---|---|
confirm | string | no | Constraints: at least 1 character. |
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}/scopes/{id}/impact
Requires the "manage-tenant" capability.
What deleting the scope would take with it: how many clients carry it and how many roles are mapped to it, each counted up to the same ceiling the list counts stop at, and whether it is a built-in scope, which its name alone decides. Two bounded index reads, whatever the tenant holds.
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 |
|---|---|---|---|
builtin | boolean | yes | True for a scope every tenant has, which is deleted only when confirm names it. |
client_assignments | object | yes | How many clients carry the scope, each of which loses it on deletion. |
client_assignments.count | integer | yes | How many items match, up to a cap. |
client_assignments.capped | boolean | yes | True when more match than count says, because counting stops at the cap. |
role_mappings | object | yes | How many roles are mapped to the scope, each unmapped on deletion. |
role_mappings.count | integer | yes | How many items match, up to a cap. |
role_mappings.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}/scopes/builtins
Requires the "manage-tenant" capability.
Every built-in scope, in the order a new tenant is given them, and whether this tenant has it. One read over the name index.
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 |
|---|---|---|---|
items | array of object | yes | Every built-in scope, in the order a new tenant is given them. |
items[] | object | yes | |
items[].name | string | yes | The scope’s name. |
items[].present | boolean | yes | False when the tenant has no scope of that name, so a restore would create 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.
POST /admin/tenants/{tenant}/scopes/restore-builtins
Requires the "manage-tenant" capability.
Creates each built-in scope the tenant is missing with the settings a new tenant is given, and answers the names it created, none when none was missing: repeating it is harmless. A name that exists is not recreated, whatever scope holds it, and that scope is not read or changed, edited or not, and the client assignments and role mappings a deletion took are not recreated. Refused with 409, creating nothing, when the missing ones would pass the tenant’s scope limit or the limit on scopes marked for every new client.
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 |
|---|---|---|---|
created | array of string | yes | The built-in scopes the call created, in order; empty when none was missing. |
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}/scopes/{id}/roles
Requires the "manage-tenant" capability.
Each role carries admin_reach, what it reaches of the admin vocabulary however deep it nests it. Derived on every read and outside the ETag.
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}/scopes/{id}/roles
Requires the "manage-tenant" capability.
More than 200 entries is refused with 400. The answer carries each role’s admin_reach, as the GET does. 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.
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.
GET /admin/tenants/{tenant}/scopes/{id}/mappers
Requires the "manage-tenant" capability.
declared names the mappers that declare the scope: what issuance runs for it while bound is empty. The ETag covers bound alone.
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 |
|---|---|---|---|
available | array of string | yes | Every claim mapper the server has. |
bound | array of string | yes | The mappers the scope uses now. |
declared | array of string | yes | The mapper names stored for the scope, including any the server no longer has. |
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}/scopes/{id}/mappers
Requires the "manage-tenant" capability.
Replaces the whole binding set for the scope. Binding an unregistered mapper name is refused with 400, listing the registry’s own known names. The answer carries declared as the GET does. 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.
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 |
|---|---|---|---|
mapper_names | array of string | yes | The mappers the scope should use. Replaces the current set. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
available | array of string | yes | Every claim mapper the server has. |
bound | array of string | yes | The mappers the scope uses now. |
declared | array of string | yes | The mapper names stored for the scope, including any the server no longer has. |
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}/scopes/{id}/clients
Requires the "manage-tenant" capability.
The clients the scope is assigned to, each by its row id, client_id, name and assignment, in row-id order — and nothing else of the client, which reading takes manage-clients.
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 client’s internal identifier. |
items[].client_id | string | yes | The client’s client_id. |
items[].name | string | yes | The client’s display name. |
items[].assignment | string | yes | How the scope is assigned to it. Constraints: one of default, optional. |
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.
PUT /admin/tenants/{tenant}/scopes/{id}/clients/{clientId}
Requires the "manage-tenant" capability.
Assigns the scope to the client as default or optional, replacing any existing assignment. A client carries at most 200 scopes: a new one past that is refused with 409, while changing one it already carries is not. Answers the client’s new ETag, since the client’s representation carries its scopes. Refused with 403 when the client’s service account 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. |
Request body
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
assignment | string | yes | default or optional. Constraints: one of default, optional. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
client_id | string | yes | The client’s internal identifier. |
scopes | array of object | yes | The client’s scopes after the change. |
scopes[] | object | yes | |
scopes[].id | string | yes | The scope’s identifier. |
scopes[].name | string | yes | The scope name. |
scopes[].assignment | string | yes | default is requested for the client without being asked for, optional only when the request names it. Constraints: one of default, optional. |
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}/scopes/{id}/clients/{clientId}
Requires the "manage-tenant" capability.
Removes the client’s assignment of the scope, whether default or optional. Refused with 409 on the tenant’s built-in admin client, which could otherwise lock every administrator of the tenant out of /authorize. Answers the client’s new ETag. Refused with 403 when the client’s service account 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.
Documentation coverage: 92 of 97 fields described (94%).