Admin API: Keys
Operations on keys 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}/keys
Requires the "manage-keys" capability.
Lists status, kid, alg, created_at and not_after — never the private half.
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. |
status | string | no | Only keys with this status. Constraints: one of active, rotating, retired. |
alg | string | no | Only keys with this algorithm. Constraints: one of RS256, ES256. |
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 key’s identifier in the admin API. |
items[].status | string | yes | active signs new tokens, rotating still verifies and is published but is not used to sign, retired is kept only until deleted. Constraints: one of active, rotating, retired. |
items[].kid | string | yes | The key id placed in the header of tokens it signs and published in the JWKS. |
items[].alg | string | yes | The signature algorithm, RS256 or ES256. Constraints: one of RS256, ES256. |
items[].created_at | string | yes | When the key was created. |
items[].not_after | string or null | yes | When the key stops being published for verification, 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.
POST /admin/tenants/{tenant}/keys
Requires the "manage-keys" capability.
Generates a key and stores it as rotating, published in JWKS immediately. Answers the key’s ETag, which promote and retire honour as If-Match.
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 |
|---|---|---|---|
alg | string | yes | The algorithm of the new key. It is created rotating; promote it to make it the one that signs. Constraints: one of RS256, ES256. |
Responses
201 Created
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The key’s identifier in the admin API. |
status | string | yes | active signs new tokens, rotating still verifies and is published but is not used to sign, retired is kept only until deleted. Constraints: one of active, rotating, retired. |
kid | string | yes | The key id placed in the header of tokens it signs and published in the JWKS. |
alg | string | yes | The signature algorithm, RS256 or ES256. Constraints: one of RS256, ES256. |
created_at | string | yes | When the key was created. |
not_after | string or null | yes | When the key stops being published for verification, 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.
POST /admin/tenants/{tenant}/keys/{id}/promote
Requires the "manage-keys" capability.
Demotes the current active key to rotating and promotes this one, atomically. If-Match is optional: a stale one, taken over the key, 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. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The key’s identifier in the admin API. |
status | string | yes | active signs new tokens, rotating still verifies and is published but is not used to sign, retired is kept only until deleted. Constraints: one of active, rotating, retired. |
kid | string | yes | The key id placed in the header of tokens it signs and published in the JWKS. |
alg | string | yes | The signature algorithm, RS256 or ES256. Constraints: one of RS256, ES256. |
created_at | string | yes | When the key was created. |
not_after | string or null | yes | When the key stops being published for verification, 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.
POST /admin/tenants/{tenant}/keys/{id}/retire
Requires the "manage-keys" capability.
Refused with 409 while the key is active (about:blank#key-active), or while a client is registered against an algorithm no remaining key would produce (#key-algorithm-needed, naming at most 20 clients as errors entries of path clients, and the number left out as one of path clients.more). If-Match is optional: a stale one, taken over the key, 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. |
Responses
200 OK
Body: application/json
| Field | Type | Required | Details |
|---|---|---|---|
id | string | yes | The key’s identifier in the admin API. |
status | string | yes | active signs new tokens, rotating still verifies and is published but is not used to sign, retired is kept only until deleted. Constraints: one of active, rotating, retired. |
kid | string | yes | The key id placed in the header of tokens it signs and published in the JWKS. |
alg | string | yes | The signature algorithm, RS256 or ES256. Constraints: one of RS256, ES256. |
created_at | string | yes | When the key was created. |
not_after | string or null | yes | When the key stops being published for verification, 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.
DELETE /admin/tenants/{tenant}/keys/{id}
Requires the "manage-keys" capability.
Deletes a retired key, which is published nowhere and signs nothing. Refused with 409 (about:blank#key-not-retired) for an active or rotating one, which POST …/retire retires first. If-Match is optional: 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. |
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: 31 of 31 fields described (100%).