{ "openapi": "3.1.0", "info": { "title": "Odudu admin API", "version": "0.0.0" }, "security": [ { "bearerAuth": [] } ], "paths": { "/admin/tenants/{tenant}/whoami": { "get": { "summary": "Requires an authenticated admin caller.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subjectId": { "type": "string", "description": "The subject the access token was issued to." }, "issuerTenantId": { "type": "string", "description": "The tenant that issued the token, which is the caller’s own tenant." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the caller holds in its own tenant, directly, through a group or nested in a role. A composite such as `tenant-admin` is reported as the capabilities it carries." }, "crossTenant": { "type": "boolean", "description": "True when the caller’s tenant is not the tenant in the path, which only a holder of `manage-tenants` may be." } }, "required": [ "subjectId", "issuerTenantId", "capabilities", "crossTenant" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "username", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose username starts with this, ignoring case." } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose email starts with this, ignoring case." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose full name starts with this, ignoring case." } }, { "name": "given_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose first name starts with this, ignoring case." } }, { "name": "family_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose last name starts with this, ignoring case." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled subjects only, `false` for disabled ones only." } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only subjects holding this role, by role id." } }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only members of this group, by group id." } }, { "name": "capability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants", "tenant-admin", "any" ], "description": "Only holders of this admin capability, `tenant-admin`, or `any` admin capability; held effectively." } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "Only subjects of this type." } }, { "name": "locked", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for subjects locked out by failed sign-ins only." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The subject’s identifier, a UUID." }, "type": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "`user` is a person, `service` is the account of a confidential client, `agent_instance` is an automated agent." }, "username": { "type": [ "string", "null" ], "description": "The name the subject signs in with, or null for a subject that does not." }, "email": { "type": [ "string", "null" ], "description": "The subject’s email address, or null." }, "enabled": { "type": "boolean", "description": "A disabled subject cannot sign in or get tokens." }, "created_at": { "type": "string", "description": "When the subject was created." }, "admin_capabilities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants", "tenant-admin" ], "description": "The admin capability, or `tenant-admin`, which holds them all." }, "direct": { "type": "boolean", "description": "True when it is assigned to the subject itself, false when it comes through a group or a role." } }, "required": [ "name", "direct" ], "additionalProperties": false }, "description": "Present when the list was filtered by `capability`: every admin capability the subject holds." } }, "required": [ "id", "type", "username", "email", "enabled", "created_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The sign-in name. Unique in the tenant, case counts." }, "email": { "type": "string", "minLength": 1, "description": "The email address, if any." } }, "required": [ "username" ], "additionalProperties": false, "examples": [ { "username": "ada", "email": "ada@example.com" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The subject’s identifier, a UUID." }, "type": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "`user` is a person, `service` is the account of a confidential client, `agent_instance` is an automated agent." }, "username": { "type": [ "string", "null" ], "description": "The name the subject signs in with, or null for a subject that does not." }, "email": { "type": [ "string", "null" ], "description": "The subject’s email address, or null." }, "enabled": { "type": "boolean", "description": "A disabled subject cannot sign in or get tokens." }, "created_at": { "type": "string", "description": "When the subject was created." } }, "required": [ "id", "type", "username", "email", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/count": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "username", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose username starts with this, ignoring case." } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose email starts with this, ignoring case." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose full name starts with this, ignoring case." } }, { "name": "given_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose first name starts with this, ignoring case." } }, { "name": "family_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only subjects whose last name starts with this, ignoring case." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled subjects only, `false` for disabled ones only." } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only subjects holding this role, by role id." } }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only members of this group, by group id." } }, { "name": "capability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants", "tenant-admin", "any" ], "description": "Only holders of this admin capability, `tenant-admin`, or `any` admin capability; held effectively." } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "Only subjects of this type." } }, { "name": "locked", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for subjects locked out by failed sign-ins only." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/username-policy": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username_editable": { "type": "boolean", "description": "Whether the tenant lets a username be changed." } }, "required": [ "username_editable" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/bulk": { "post": { "summary": "Requires the \"manage-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": [ "disable", "enable", "delete", "end-sessions" ], "description": "What to do to every listed subject: `disable`, `enable`, `delete` or `end-sessions`." }, "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The subjects to act on, at most 100." } }, "required": [ "action", "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The subject." }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The HTTP status this subject’s part of the call would have had alone." }, "type": { "type": "string", "description": "The problem type when it was refused." }, "detail": { "type": "string", "description": "Why it was refused." }, "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "For `end-sessions`, how many sessions were ended." } }, "required": [ "id", "status" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The subject’s identifier, a UUID." }, "type": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "`user` is a person, `service` is the account of a confidential client, `agent_instance` is an automated agent." }, "username": { "type": [ "string", "null" ], "description": "The name the subject signs in with, or null for a subject that does not." }, "email": { "type": [ "string", "null" ], "description": "The subject’s email address, or null." }, "enabled": { "type": "boolean", "description": "A disabled subject cannot sign in or get tokens." }, "created_at": { "type": "string", "description": "When the subject was created." } }, "required": [ "id", "type", "username", "email", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "description": "A new sign-in name, when the tenant allows renaming." }, "email": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "A new email address, or null to remove it." }, "enabled": { "type": "boolean", "description": "Whether the subject may sign in." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The subject’s identifier, a UUID." }, "type": { "type": "string", "enum": [ "user", "service", "agent_instance" ], "description": "`user` is a person, `service` is the account of a confidential client, `agent_instance` is an automated agent." }, "username": { "type": [ "string", "null" ], "description": "The name the subject signs in with, or null for a subject that does not." }, "email": { "type": [ "string", "null" ], "description": "The subject’s email address, or null." }, "enabled": { "type": "boolean", "description": "A disabled subject cannot sign in or get tokens." }, "created_at": { "type": "string", "description": "When the subject was created." } }, "required": [ "id", "type", "username", "email", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/profile": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s full name, as they would write it." }, "given_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The first name." }, "family_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The last name." }, "middle_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The middle name." }, "nickname": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "A casual name." }, "preferred_username": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The name the user prefers to be addressed by; separate from the sign-in username." }, "profile": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s profile page." }, "picture": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s picture." }, "website": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s web page." }, "gender": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s gender, in the user’s own words." }, "birthdate": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The birth date as `YYYY-MM-DD`, or `YYYY` alone." }, "zoneinfo": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The time zone as an IANA name, such as `Europe/Berlin`." }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The preferred language as a BCP 47 tag, such as `en-GB`." }, "phone_number": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The telephone number, ideally in E.164 form." }, "phone_number_verified": { "type": "boolean", "description": "Whether the phone number was verified." }, "email_verified": { "type": "boolean", "description": "Whether the email address was verified." }, "address_formatted": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The whole postal address as one multi-line string." }, "address_street": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The street address." }, "address_locality": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The city or locality." }, "address_region": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The state, province or region." }, "address_postal_code": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The postal code." }, "address_country": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The country." }, "profile_updated_at": { "type": [ "string", "null" ], "description": "When the profile last changed, or null." } }, "required": [ "name", "given_name", "family_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "phone_number", "phone_number_verified", "email_verified", "address_formatted", "address_street", "address_locality", "address_region", "address_postal_code", "address_country", "profile_updated_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s full name, as they would write it." }, "given_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The first name." }, "family_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The last name." }, "middle_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The middle name." }, "nickname": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "A casual name." }, "preferred_username": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The name the user prefers to be addressed by; separate from the sign-in username." }, "profile": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s profile page." }, "picture": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s picture." }, "website": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s web page." }, "gender": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s gender, in the user’s own words." }, "birthdate": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The birth date as `YYYY-MM-DD`, or `YYYY` alone." }, "zoneinfo": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The time zone as an IANA name, such as `Europe/Berlin`." }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The preferred language as a BCP 47 tag, such as `en-GB`." }, "phone_number": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The telephone number, ideally in E.164 form." }, "phone_number_verified": { "type": "boolean", "description": "Whether the phone number was verified." }, "email_verified": { "type": "boolean", "description": "Whether the email address was verified." }, "address_formatted": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The whole postal address as one multi-line string." }, "address_street": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The street address." }, "address_locality": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The city or locality." }, "address_region": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The state, province or region." }, "address_postal_code": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The postal code." }, "address_country": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The country." }, "email": { "description": "Refused here: change the email address with the subject’s own `email`." }, "username": { "description": "Refused here: change the username with the subject’s own `username`." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s full name, as they would write it." }, "given_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The first name." }, "family_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The last name." }, "middle_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The middle name." }, "nickname": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "A casual name." }, "preferred_username": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The name the user prefers to be addressed by; separate from the sign-in username." }, "profile": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s profile page." }, "picture": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s picture." }, "website": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The address of the user’s web page." }, "gender": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The user’s gender, in the user’s own words." }, "birthdate": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The birth date as `YYYY-MM-DD`, or `YYYY` alone." }, "zoneinfo": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The time zone as an IANA name, such as `Europe/Berlin`." }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The preferred language as a BCP 47 tag, such as `en-GB`." }, "phone_number": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The telephone number, ideally in E.164 form." }, "phone_number_verified": { "type": "boolean", "description": "Whether the phone number was verified." }, "email_verified": { "type": "boolean", "description": "Whether the email address was verified." }, "address_formatted": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The whole postal address as one multi-line string." }, "address_street": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The street address." }, "address_locality": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The city or locality." }, "address_region": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The state, province or region." }, "address_postal_code": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The postal code." }, "address_country": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ], "description": "The country." }, "profile_updated_at": { "type": [ "string", "null" ], "description": "When the profile last changed, or null." } }, "required": [ "name", "given_name", "family_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "phone_number", "phone_number_verified", "email_verified", "address_formatted", "address_street", "address_locality", "address_region", "address_postal_code", "address_country", "profile_updated_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/credentials": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The credential’s identifier, for deleting it. Absent for a password." }, "type": { "type": "string", "enum": [ "password", "totp", "webauthn", "recovery-code" ], "description": "`password`, `totp` (an authenticator app), `webauthn` (a passkey) or `recovery-code`." }, "created_at": { "type": "string", "description": "When the credential was set up." }, "expired": { "type": "boolean", "description": "For a password, whether the tenant’s maximum password age has passed." }, "recovery_code_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "For recovery codes, how many unused codes remain." } }, "required": [ "type", "created_at" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/credentials/{credentialId}": { "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "credentialId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "end_sessions", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`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." } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/consents": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The client’s internal identifier." }, "client_key": { "type": "string", "description": "The client’s `client_id`." }, "scope_names": { "type": "array", "items": { "type": "string" }, "description": "The scopes the user agreed to." }, "granted_at": { "type": "string", "description": "When the user agreed." } }, "required": [ "client_id", "client_key", "scope_names", "granted_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/consents/{clientId}": { "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "clientId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/password": { "post": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "password": { "type": "string" } }, "required": [ "password" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/password-reset": { "post": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/verification": { "post": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/actions-email": { "post": { "summary": "Requires the \"manage-users\" capability.", "description": "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 `409`s 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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "update-password", "configure-totp", "configure-passkey", "generate-recovery-codes" ] }, "description": "The required actions after the change." } }, "required": [ "actions" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/lockout": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locked": { "type": "boolean" }, "locked_until": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_failure_at": { "type": [ "string", "null" ] } }, "required": [ "locked", "locked_until", "failure_count", "last_failure_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/recovery-codes": { "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "require_new_set", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`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." } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/required-actions": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "update-password", "configure-totp", "configure-passkey", "generate-recovery-codes" ] }, "description": "The required actions after the change." } }, "required": [ "actions" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-users\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "update-password", "configure-totp", "configure-passkey", "generate-recovery-codes" ] }, "description": "The required actions after the change." } }, "required": [ "actions" ], "additionalProperties": false, "examples": [ { "actions": [ "update-password", "configure-totp" ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "update-password", "configure-totp", "configure-passkey", "generate-recovery-codes" ] }, "description": "The required actions after the change." } }, "required": [ "actions" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/roles": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." } }, "required": [ "id", "name", "client_id", "client_key" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The identifiers of every role the subject should hold. Replaces the current set." } }, "required": [ "role_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." } }, "required": [ "id", "name", "client_id", "client_key" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/effective-roles": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "via": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "direct" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "group" }, "group_id": { "type": "string" }, "group_path": { "type": "string" } }, "required": [ "kind", "group_id", "group_path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composite" }, "parent_role_id": { "type": "string" }, "parent_name": { "type": "string" } }, "required": [ "kind", "parent_role_id", "parent_name" ], "additionalProperties": false } ] }, "description": "How the subject holds the role: directly, through a group, or through a composite role." } }, "required": [ "id", "name", "client_id", "client_key", "via" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/admin-capabilities": { "get": { "summary": "Requires the \"view-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "via": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "direct" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "group" }, "group_id": { "type": "string" }, "group_path": { "type": "string" } }, "required": [ "kind", "group_id", "group_path" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composite" }, "parent_role_id": { "type": "string" }, "parent_name": { "type": "string" } }, "required": [ "kind", "parent_role_id", "parent_name" ], "additionalProperties": false } ] }, "description": "How the subject holds the role: directly, through a group, or through a composite role." } }, "required": [ "id", "name", "client_id", "client_key", "via" ], "additionalProperties": false }, "description": "The roles that carry admin capabilities, with how the subject holds each." }, "complete": { "type": "boolean", "description": "False when the list was cut at its bound." } }, "required": [ "items", "complete" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/groups": { "get": { "summary": "Requires the \"view-users\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-users\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "group_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" } } }, "required": [ "group_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/sessions": { "get": { "summary": "Requires the \"manage-sessions\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The session’s identifier." }, "created_at": { "type": "string", "description": "When the user signed in." }, "last_active_at": { "type": "string", "description": "When the session last did anything." }, "remembered": { "type": "boolean", "description": "Whether the user chose to stay signed in, which gives the session the longer remember-me lifetimes." }, "client_ids": { "type": "array", "items": { "type": "string" }, "description": "The clients the session has signed the user in to." } }, "required": [ "id", "created_at", "last_active_at", "remembered", "client_ids" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-sessions\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many sessions were ended." } }, "required": [ "ended" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/sessions/{sid}": { "delete": { "summary": "Requires the \"manage-sessions\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "sid", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/grants": { "get": { "summary": "Requires the \"manage-sessions\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The grant’s identifier." }, "client_id": { "type": "string", "description": "The client the grant was issued to, by its internal id." }, "client_key": { "type": "string", "description": "That client’s `client_id`." }, "scope": { "type": "string", "description": "The scopes the grant covers, space-separated." }, "created_at": { "type": "string", "description": "When the user authorized it." }, "session_id": { "type": [ "string", "null" ], "description": "The session it is tied to, or null for an offline grant." }, "offline": { "type": "boolean", "description": "True when the grant outlives the user’s session (the `offline_access` scope)." }, "refresh_expires_at": { "type": [ "string", "null" ], "description": "When its refresh token expires, or null." } }, "required": [ "id", "client_id", "client_key", "scope", "created_at", "session_id", "offline", "refresh_expires_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/subjects/{id}/grants/{clientId}": { "delete": { "summary": "Requires the \"manage-sessions\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "clientId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many grants were revoked." } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/sessions": { "get": { "summary": "Requires the \"manage-sessions\" capability.", "description": "Every live session in the tenant, whoever holds it, in id order; `?client=` narrows it to the sessions holding a grant through that client (its row id).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only sessions that signed the user in to this client, by its internal id." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The session’s identifier." }, "created_at": { "type": "string", "description": "When the user signed in." }, "last_active_at": { "type": "string", "description": "When the session last did anything." }, "remembered": { "type": "boolean", "description": "Whether the user chose to stay signed in, which gives the session the longer remember-me lifetimes." }, "client_ids": { "type": "array", "items": { "type": "string" }, "description": "The clients the session has signed the user in to." }, "subject_id": { "type": "string", "description": "The user the session belongs to." }, "username": { "type": [ "string", "null" ], "description": "That user’s username, or null." } }, "required": [ "id", "created_at", "last_active_at", "remembered", "client_ids", "subject_id", "username" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-sessions\" capability.", "description": "Ends the tenant’s live sessions, each as `DELETE …/subjects/{id}/sessions/{sid}` ends one, at most 500 a call in id order; `remaining` says how many are still live within reach, so a caller repeats the call until it is 0. A session whose subject holds an admin capability the caller does not is left alone and counted under `beyond_ceiling` (the target ceiling, run over the tenant).", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ended": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many sessions this call ended." }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many are left; repeat the call until it is 0." }, "beyond_ceiling": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many belong to users holding an admin capability the caller does not, which are left alone." } }, "required": [ "ended", "remaining", "beyond_ceiling" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/sessions/count": { "get": { "summary": "Requires the \"manage-sessions\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only sessions that signed the user in to this client, by its internal id." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants": { "get": { "summary": "Requires the \"manage-tenants\" capability.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only tenants whose name starts with this." } }, { "name": "display_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only tenants whose display name starts with this." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled tenants only, `false` for disabled ones." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The tenant’s internal identifier, a UUID." }, "name": { "type": "string", "description": "The name in the tenant’s addresses and issuer." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people on sign-in pages, or null." }, "enabled": { "type": "boolean", "description": "A disabled tenant refuses every sign-in and token request." }, "created_at": { "type": "string", "description": "When the tenant was created." } }, "required": [ "id", "name", "display_name", "enabled", "created_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-tenants\" capability.", "description": "A `display_name` is trimmed, and a blank one is stored as none (`null`), which the tenant’s pages replace with its name.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The tenant name, used in every address of the tenant (`/tenants/{name}/...`). 1 to 63 lowercase letters, digits or hyphens, not starting or ending with a hyphen." }, "display_name": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "A friendly name for people. Null when none was given." } }, "required": [ "name" ], "additionalProperties": false, "examples": [ { "name": "acme", "display_name": "Acme Corporation" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The tenant’s internal identifier, a UUID." }, "name": { "type": "string", "description": "The name in the tenant’s addresses and issuer." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people on sign-in pages, or null." }, "enabled": { "type": "boolean", "description": "A disabled tenant refuses every sign-in and token request." }, "created_at": { "type": "string", "description": "When the tenant was created." } }, "required": [ "id", "name", "display_name", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/count": { "get": { "summary": "Requires the \"manage-tenants\" capability.", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only tenants whose name starts with this." } }, { "name": "display_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only tenants whose display name starts with this." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled tenants only, `false` for disabled ones." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenant-imports": { "post": { "summary": "Requires the \"manage-tenants\" capability.", "description": "A set over 200 entries, more than 1,000 scopes, more than 200 scopes marked for every new client, a client given more than 200 scopes, or more than 200 default roles or groups is refused in the same `400`, naming the limit and the count. Creates a new tenant from a document `GET /admin/tenants/{tenant}/export` answered, with its own signing key and a fresh secret for each confidential client, answered once here. A blank `display_name`, in the request or the document, is stored as none. Every problem with the request is refused together in one `400` whose `errors` lists each by its JSON path; a name already in use is refused with `409`.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the tenant to create." }, "display_name": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "A friendly name for the new tenant." }, "document": { "description": "A tenant document, as GET /admin/tenants/{tenant}/export answers it." } }, "required": [ "name", "document" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string", "description": "The tenant’s internal identifier, a UUID." }, "name": { "type": "string", "description": "The name in the tenant’s addresses and issuer." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people on sign-in pages, or null." }, "enabled": { "type": "boolean", "description": "A disabled tenant refuses every sign-in and token request." }, "created_at": { "type": "string", "description": "When the tenant was created." } }, "required": [ "id", "name", "display_name", "enabled", "created_at" ], "additionalProperties": false, "description": "The tenant that was created." }, "client_secrets": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The imported client." }, "secret": { "type": "string", "description": "Its newly generated secret. Shown only in this response." } }, "required": [ "client_id", "secret" ], "additionalProperties": false }, "description": "The secrets generated for the imported confidential clients." } }, "required": [ "tenant", "client_secrets" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The tenant’s internal identifier, a UUID." }, "name": { "type": "string", "description": "The name in the tenant’s addresses and issuer." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people on sign-in pages, or null." }, "enabled": { "type": "boolean", "description": "A disabled tenant refuses every sign-in and token request." }, "created_at": { "type": "string", "description": "When the tenant was created." } }, "required": [ "id", "name", "display_name", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Amends display_name and enabled. A `display_name` is trimmed, and a blank one is stored as none (`null`). `name` is refused with 400: it is already in the issuer URL of every token this tenant has minted. Disabling the system tenant is refused with 409, since every cross-tenant administrator authenticates against it. Once a disable of any other has committed, every live session in it is ended in batches of 500, each its own transaction, queuing a Back-Channel Logout Token for each relying party that used one; the answer comes when all have ended. A batch that fails is answered with `500` `sessions-not-ended`: the disable stands, and sending `enabled: false` again ends the rest. Its discovery document and key set stay served.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The tenant’s internal identifier, a UUID." }, "name": { "type": "string", "description": "The name in the tenant’s addresses and issuer." }, "display_name": { "type": [ "string", "null" ], "description": "The name shown to people on sign-in pages, or null." }, "enabled": { "type": "boolean", "description": "A disabled tenant refuses every sign-in and token request." }, "created_at": { "type": "string", "description": "When the tenant was created." } }, "required": [ "id", "name", "display_name", "enabled", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenants\" capability.", "description": "Deletes the tenant and every row it holds, in one transaction, recorded in the `system` tenant’s trail as `tenant.delete`. `confirm` must be the tenant’s own name, refused with `400` naming it otherwise. Refused with `409` for `system`; with `409` `tenant-enabled` until the tenant is disabled, which ends its sessions and queues their Logout Tokens; with `409` `sessions-live` while any session is still live; and with `409` `logout-deliveries-pending` until each of those tokens is delivered or has spent every attempt. The tenant’s keys go with it. Refused with `403` when the tenant’s subjects hold an admin capability the caller does not (the target ceiling, over every subject at once).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "confirm", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/export": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "A tenant too large for one document is refused with `413`: more than 20,000 clients, roles or groups, 200,000 rows of a link table, or one role, group, scope or subject holding more than 200 of a set, which an import would refuse. The tenant’s configuration, every reference by name, with no secret in it: each secret a reader would expect is named under `omitted` by its JSON path. Additionally requires `manage-clients`, the capability every other client read requires, refused with `403` otherwise. `?include=subjects` adds subjects and additionally requires `view-users`, refused with `403` otherwise and with `413` above 10,000 subjects.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "const": "subjects" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.odudu.tenant+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1, "description": "The document format version; always 1." }, "settings": { "type": "object", "properties": { "display_name": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "The name shown to people on sign-in pages." }, "enabled": { "type": "boolean", "description": "Whether the tenant accepts sign-ins and token requests." }, "reset_password_allowed": { "type": "boolean", "description": "Whether users may ask for a password reset link by mail." }, "sso_session_idle_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a browser session may sit idle before it ends." }, "sso_session_max_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The longest a browser session lasts, however active." }, "password_min_length": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The fewest characters a password may have." }, "password_require_digit": { "type": "boolean", "description": "Whether a password must contain a digit." }, "password_require_uppercase": { "type": "boolean", "description": "Whether a password must contain an upper-case letter." }, "password_require_lowercase": { "type": "boolean", "description": "Whether a password must contain a lower-case letter." }, "password_require_special": { "type": "boolean", "description": "Whether a password must contain a character that is not a letter or digit." }, "password_not_username": { "type": "boolean", "description": "Whether a password may not equal the username." }, "password_not_email": { "type": "boolean", "description": "Whether a password may not equal the email address." }, "password_history_depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many previous passwords a user may not reuse. 0 keeps none." }, "password_max_age_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days before a password must be changed. 0 means it never expires." }, "otp_required": { "type": "boolean", "description": "Whether every user must set up a one-time-code authenticator." }, "brute_force_max_failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Failed sign-ins in a row before the account is locked out." }, "brute_force_lockout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a lockout lasts." }, "brute_force_max_lockout_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The longest a lockout can grow to when it is tripped again." }, "brute_force_failure_reset_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long without a failed sign-in before the count starts again." }, "max_clients": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The most clients the tenant may hold." }, "max_sessions_per_browser": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The most sessions one browser may hold at once." }, "remember_me_allowed": { "type": "boolean", "description": "Whether the sign-in form offers to stay signed in." }, "remember_me_idle_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a remembered session may sit idle." }, "remember_me_max_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The longest a remembered session lasts." }, "audit_retention_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many days audit events are kept before `odudu reap` deletes them." }, "username_editable": { "type": "boolean", "description": "Whether a username may be changed after it is set." }, "access_token_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long an access token lives unless the client says otherwise." }, "id_token_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long an ID token lives unless the client says otherwise." }, "refresh_token_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a refresh token lives unless the client says otherwise." }, "authorization_code_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long an authorization code can be redeemed." }, "login_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a started sign-in may take to finish." }, "verify_email_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a mailed email-verification link works." }, "reset_password_ttl_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a mailed password-reset link works." }, "login_with_email": { "type": "boolean", "description": "Whether a user may sign in with the email address instead of the username." }, "audit_event_types": { "type": "array", "items": { "type": "string" }, "description": "The audit event types the tenant stores." } }, "required": [ "display_name", "enabled", "reset_password_allowed", "sso_session_idle_seconds", "sso_session_max_seconds", "password_min_length", "password_require_digit", "password_require_uppercase", "password_require_lowercase", "password_require_special", "password_not_username", "password_not_email", "password_history_depth", "password_max_age_days", "otp_required", "brute_force_max_failures", "brute_force_lockout_seconds", "brute_force_max_lockout_seconds", "brute_force_failure_reset_seconds", "max_clients", "max_sessions_per_browser", "remember_me_allowed", "remember_me_idle_seconds", "remember_me_max_seconds", "audit_retention_days", "username_editable", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "authorization_code_ttl_seconds", "login_ttl_seconds", "verify_email_ttl_seconds", "reset_password_ttl_seconds", "login_with_email", "audit_event_types" ], "additionalProperties": false, "description": "The tenant’s settings." }, "flow": { "type": "array", "items": { "type": "object", "properties": { "authenticator": { "type": "string", "description": "The sign-in step to run." }, "requirement": { "type": "string", "enum": [ "required", "alternative", "conditional", "disabled" ], "description": "`required`, `alternative`, `conditional` or `disabled`." } }, "required": [ "authenticator", "requirement" ], "additionalProperties": false }, "description": "The sign-in flow, in order." }, "clients": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "A display name for people, shown for example on the consent screen." }, "description": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "redirect_uris": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "service_account_roles": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Only roles whose name starts with this." }, "client": { "type": [ "string", "null" ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } }, "required": [ "name", "client" ], "additionalProperties": false } } }, "required": [ "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "service_account_roles" ], "additionalProperties": false }, "description": "The tenant’s clients. Secrets are never exported." }, "roles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The role name." }, "client": { "type": [ "string", "null" ], "description": "The `client_id` the role belongs to, or null for a tenant-wide role." }, "description": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "Free text for administrators, or null." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether new users are given the role." }, "builtin": { "type": "boolean", "description": "True for a role every tenant has, such as the admin roles." }, "composites": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Only roles whose name starts with this." }, "client": { "type": [ "string", "null" ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } }, "required": [ "name", "client" ], "additionalProperties": false }, "description": "The roles this role contains." } }, "required": [ "name", "client", "description", "default_for_new_subjects", "builtin", "composites" ], "additionalProperties": false }, "description": "The tenant’s roles." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The group’s place in the hierarchy, such as `/staff/eu`." }, "description": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "Free text for administrators, or null." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether new users join the group." }, "roles": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Only roles whose name starts with this." }, "client": { "type": [ "string", "null" ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } }, "required": [ "name", "client" ], "additionalProperties": false }, "description": "The roles every member of the group is given." } }, "required": [ "path", "description", "default_for_new_subjects", "roles" ], "additionalProperties": false }, "description": "The tenant’s groups." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The scope name clients request." }, "description": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "Free text for administrators, or null." }, "include_in_id_token": { "type": "boolean", "description": "Whether its claims appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether its claims appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "How every new client gets the scope, or null for neither." }, "consent_text": { "anyOf": [ { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "The sentence the consent screen shows for it, or null." }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where it sorts on the consent screen; lowest first." }, "builtin": { "type": "boolean", "description": "True for a scope every tenant has." }, "roles": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Only roles whose name starts with this." }, "client": { "type": [ "string", "null" ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } }, "required": [ "name", "client" ], "additionalProperties": false }, "description": "The roles the scope carries into tokens." }, "mappers": { "type": "array", "items": { "type": "string" }, "description": "The claim mappers the scope uses." }, "clients": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string" }, "assignment": { "type": "string", "enum": [ "default", "optional" ] } }, "required": [ "client_id", "assignment" ], "additionalProperties": false }, "description": "The clients the scope is assigned to, by `client_id`." } }, "required": [ "name", "description", "include_in_id_token", "include_in_access_token", "default_client_assignment", "consent_text", "display_order", "builtin", "roles", "mappers", "clients" ], "additionalProperties": false }, "description": "The tenant’s client scopes." }, "registration_policy": { "type": "object", "properties": { "registration_allowed": { "type": "boolean", "description": "Whether people may register themselves." }, "verify_email": { "type": "boolean", "description": "Whether a registered address must be verified before sign-in." }, "client_registration_policy": { "type": "string", "enum": [ "disabled", "open", "token" ], "description": "Who may register clients dynamically: nobody (`disabled`), anybody (`open`) or the holder of an initial access token (`token`)." } }, "required": [ "registration_allowed", "verify_email", "client_registration_policy" ], "additionalProperties": false, "description": "Who may register themselves and register clients." }, "smtp": { "anyOf": [ { "type": "object", "properties": { "host": { "type": "string", "description": "The SMTP relay’s host." }, "port": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The relay’s port." }, "from_address": { "type": "string", "description": "The address mail is sent from." }, "username": { "type": [ "string", "null" ], "description": "The user name for the relay, or null. The password is never exported." }, "starttls": { "type": "boolean", "description": "Whether STARTTLS is required." } }, "required": [ "host", "port", "from_address", "username", "starttls" ], "additionalProperties": false }, { "type": "null" } ], "description": "The tenant’s mail relay, or null when it has none." }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The sign-in name." }, "email": { "type": [ "string", "null" ], "description": "The email address, or null." }, "enabled": { "type": "boolean", "description": "Whether the subject may sign in." }, "profile": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "given_name": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "family_name": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "middle_name": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "nickname": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "preferred_username": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } ] }, { "type": "null" } ] }, "profile": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "picture": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "birthdate": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "zoneinfo": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "phone_number": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "phone_number_verified": { "type": "boolean" }, "email_verified": { "type": "boolean" }, "address_formatted": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "address_street": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "address_locality": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "address_region": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "address_postal_code": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "address_country": { "anyOf": [ { "type": "string", "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] } }, "required": [ "name", "given_name", "family_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", "phone_number", "phone_number_verified", "email_verified", "address_formatted", "address_street", "address_locality", "address_region", "address_postal_code", "address_country" ], "additionalProperties": false, "description": "The standard profile claims." }, "roles": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Only roles whose name starts with this." }, "client": { "type": [ "string", "null" ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } }, "required": [ "name", "client" ], "additionalProperties": false }, "description": "The roles the subject holds directly." }, "groups": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The groups the subject belongs to, by path." }, "required_actions": { "type": "array", "items": { "type": "string", "enum": [ "update-password", "configure-totp", "configure-passkey", "generate-recovery-codes" ] }, "description": "The actions the subject must complete at next sign-in." } }, "required": [ "username", "email", "enabled", "profile", "roles", "groups", "required_actions" ], "additionalProperties": false }, "description": "The tenant’s users, only when requested with `include=subjects`." }, "omitted": { "type": "array", "items": { "type": "string" }, "description": "What the document leaves out on purpose, such as secrets and credentials." } }, "required": [ "version", "settings", "flow", "clients", "roles", "groups", "scopes", "registration_policy", "smtp", "omitted" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/settings": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, { "type": "null" } ] }, "description": "Every tenant setting by name with its current value: lifetimes, password and lockout rules, which sign-in features are on, retention." } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-tenant\" capability.", "description": "`display_name` is trimmed, and a blank one is stored as none (`null`). `enabled: false` ends every live session in the tenant, after the change has committed and in batches, as `PATCH /admin/tenants/{tenant}` does.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "The settings to change, by name, each with its new value. A name the tenant does not have, or a value outside its range, is refused naming it.", "examples": [ { "password_min_length": 12, "registration_allowed": true } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, { "type": "null" } ] }, "description": "Every tenant setting by name with its current value: lifetimes, password and lockout rules, which sign-in features are on, retention." } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients": { "get": { "summary": "Requires the \"manage-clients\" capability.", "description": "`service_account_admin_reach` is what the client’s service account holds of the admin capabilities, which every write on the client is judged against; derived on every read and outside the `ETag`, empty for a client with no service account. `client_id_exact` finds the one client whose `client_id` is exactly that, through the unique index.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only clients whose `client_id` starts with this." } }, { "name": "client_id_exact", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "The one client with exactly this `client_id`." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only clients whose name starts with this." } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "confidential" ], "description": "Only clients of this type." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled clients only." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The client's internal identifier, a UUID. It names the client in admin API paths such as `/clients/{id}`; it is not the OAuth `client_id`." }, "client_id": { "type": "string", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "description": "A display name for people, shown for example on the consent screen." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "created_at": { "type": "string", "description": "When the client was created, as an ISO 8601 date and time." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "When the secret that a rotation replaced stops authenticating, or null when no rotation kept one. The secret itself is never shown." }, "builtin_admin": { "type": "boolean", "description": "True for the tenant’s built-in admin console client, which cannot be deleted and is limited in what can be amended." }, "service_subject_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The service account a confidential client authenticates as, or null when it has none." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The scopes assigned to the client and whether each is `default` (always requested) or `optional` (only when asked for)." }, "service_account_admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "created_at", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "previous_secret_expires_at", "builtin_admin", "service_subject_id", "scopes", "service_account_admin_reach" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-clients\" capability.", "description": "A list on the client (`redirect_uris`, `web_origins`, `post_logout_redirect_uris`, `audiences`, `client_credentials_scopes`) holds at most 200 entries, refused with `400` naming the field, how many it held and how many it may. A write refuses only a list it changes: a client stored over the limit is amended in its other fields as it is.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" } }, "required": [ "client_id" ], "additionalProperties": {}, "description": "RFC 7591 client metadata, plus any field PATCH /clients/{id} amends (audiences, web_origins, token lifetimes, …). Any other field is refused with 400 naming it, never ignored.", "examples": [ { "client_id": "web-app", "name": "Web app", "redirect_uris": [ "https://app.example.com/callback" ], "grant_types": [ "authorization_code", "refresh_token" ], "token_endpoint_auth_method": "none" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The client's internal identifier, a UUID. It names the client in admin API paths such as `/clients/{id}`; it is not the OAuth `client_id`." }, "client_id": { "type": "string", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "description": "A display name for people, shown for example on the consent screen." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "created_at": { "type": "string", "description": "When the client was created, as an ISO 8601 date and time." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "When the secret that a rotation replaced stops authenticating, or null when no rotation kept one. The secret itself is never shown." }, "builtin_admin": { "type": "boolean", "description": "True for the tenant’s built-in admin console client, which cannot be deleted and is limited in what can be amended." }, "service_subject_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The service account a confidential client authenticates as, or null when it has none." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The scopes assigned to the client and whether each is `default` (always requested) or `optional` (only when asked for)." }, "service_account_admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } }, "client_secret": { "type": "string", "description": "The new secret. Shown only in this response." } }, "required": [ "id", "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "created_at", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "previous_secret_expires_at", "builtin_admin", "service_subject_id", "scopes", "service_account_admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/count": { "get": { "summary": "Requires the \"manage-clients\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only clients whose `client_id` starts with this." } }, { "name": "client_id_exact", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "The one client with exactly this `client_id`." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only clients whose name starts with this." } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "confidential" ], "description": "Only clients of this type." } }, { "name": "enabled", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` for enabled clients only." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}": { "get": { "summary": "Requires the \"manage-clients\" capability.", "description": "`service_account_admin_reach` is what the client’s service account holds of the admin capabilities, which every write on the client is judged against; derived on every read and outside the `ETag`, empty for a client with no service account.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The client's internal identifier, a UUID. It names the client in admin API paths such as `/clients/{id}`; it is not the OAuth `client_id`." }, "client_id": { "type": "string", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "description": "A display name for people, shown for example on the consent screen." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "created_at": { "type": "string", "description": "When the client was created, as an ISO 8601 date and time." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "When the secret that a rotation replaced stops authenticating, or null when no rotation kept one. The secret itself is never shown." }, "builtin_admin": { "type": "boolean", "description": "True for the tenant’s built-in admin console client, which cannot be deleted and is limited in what can be amended." }, "service_subject_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The service account a confidential client authenticates as, or null when it has none." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The scopes assigned to the client and whether each is `default` (always requested) or `optional` (only when asked for)." }, "service_account_admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "created_at", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "previous_secret_expires_at", "builtin_admin", "service_subject_id", "scopes", "service_account_admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-clients\" capability.", "description": "Refused with `403` when the client’s service account holds an admin capability the caller does not (the target ceiling). A list on the client (`redirect_uris`, `web_origins`, `post_logout_redirect_uris`, `audiences`, `client_credentials_scopes`) holds at most 200 entries, refused with `400` naming the field, how many it held and how many it may. A write refuses only a list it changes: a client stored over the limit is amended in its other fields as it is.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The client's internal identifier, a UUID. It names the client in admin API paths such as `/clients/{id}`; it is not the OAuth `client_id`." }, "client_id": { "type": "string", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "description": "A display name for people, shown for example on the consent screen." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "created_at": { "type": "string", "description": "When the client was created, as an ISO 8601 date and time." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "When the secret that a rotation replaced stops authenticating, or null when no rotation kept one. The secret itself is never shown." }, "builtin_admin": { "type": "boolean", "description": "True for the tenant’s built-in admin console client, which cannot be deleted and is limited in what can be amended." }, "service_subject_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The service account a confidential client authenticates as, or null when it has none." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The scopes assigned to the client and whether each is `default` (always requested) or `optional` (only when asked for)." }, "service_account_admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "created_at", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "previous_secret_expires_at", "builtin_admin", "service_subject_id", "scopes", "service_account_admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-clients\" capability.", "description": "Refused with `403` when the client’s service account holds an admin capability the caller does not (the target ceiling). Deletes every role scoped to the client with it, and is refused with `403` too when what those roles reach includes 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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/secret": { "post": { "summary": "Requires the \"manage-clients\" capability.", "description": "Answers the new secret once. `grace_seconds` (0 to 604800, default 0) keeps the secret it replaces authenticating that long beside it, and the response states when it stops in `previous_secret_expires_at`. Refused with `403` when the client’s service account holds an admin capability the caller does not (the target ceiling).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "grace_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 604800 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The client's internal identifier, a UUID. It names the client in admin API paths such as `/clients/{id}`; it is not the OAuth `client_id`." }, "client_id": { "type": "string", "description": "The `client_id` the application sends to the authorization and token endpoints. Chosen when the client is created and unique within the tenant." }, "name": { "type": "string", "description": "A display name for people, shown for example on the consent screen." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null when none was set." }, "type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` for an application that cannot keep a secret (a single-page or native app), which must use PKCE; `confidential` for one that authenticates at the token endpoint." }, "enabled": { "type": "boolean", "description": "A disabled client cannot start a sign-in or obtain tokens, and tokens already issued to it stop being accepted." }, "full_scope_allowed": { "type": "boolean", "description": "When true the client's tokens carry every role the user holds. When false, a role reaches a token only through a scope the client is assigned." }, "registration_origin": { "type": "string", "enum": [ "seeded", "anonymous", "token", "operator" ], "description": "How the client came to exist: `seeded` by `odudu seed` or `odudu init`, `anonymous` or `token` through dynamic registration, or `operator` through the admin API." }, "created_at": { "type": "string", "description": "When the client was created, as an ISO 8601 date and time." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the authorization server may send the user back to after sign-in. A request naming any other address is refused." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use at the token endpoint, such as `authorization_code`, `refresh_token`, `client_credentials`." }, "token_endpoint_auth_method": { "type": "string", "description": "How a confidential client authenticates at the token endpoint, for example `client_secret_basic`, `client_secret_post` or `private_key_jwt`." }, "audiences": { "type": "array", "items": { "type": "string" }, "description": "The audiences (`aud`) added to the access tokens issued to this client, besides the issuer." }, "access_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's access tokens live, in seconds. Null uses the tenant's setting of the same name." }, "id_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's ID tokens live, in seconds. Null uses the tenant's setting of the same name." }, "refresh_token_ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long this client's refresh tokens live, in seconds. Null uses the tenant's setting of the same name." }, "client_credentials_scopes": { "type": "array", "items": { "type": "string" }, "description": "The scopes the client may request with the `client_credentials` grant, where it acts as itself." }, "web_origins": { "type": "array", "items": { "type": "string" }, "description": "The browser origins allowed to call the token and UserInfo endpoints from JavaScript (CORS)." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The addresses the user may be sent to after a logout the client started." }, "jwks": { "anyOf": [ {}, { "type": "null" } ], "description": "The public keys the client authenticates with when its method is `private_key_jwt`, as a JWK Set. Null when it uses `jwks_uri` or a secret." }, "jwks_uri": { "type": [ "string", "null" ], "description": "The address the server fetches the client public keys from, instead of holding them in `jwks`." }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client page the user agent loads to tell the client the user signed out (front-channel logout)." }, "backchannel_logout_uri": { "type": [ "string", "null" ], "description": "The client endpoint the server posts a logout token to when a session ends (back-channel logout)." }, "frontchannel_logout_session_required": { "type": "boolean", "description": "Whether the front-channel logout request carries the session id (`sid`) and issuer." }, "backchannel_logout_session_required": { "type": "boolean", "description": "Whether the back-channel logout token carries the session id (`sid`)." }, "consent_required": { "type": "boolean", "description": "Whether the user must approve what the client asks for on a consent screen before tokens are issued." }, "token_exchange_impersonation_allowed": { "type": "boolean", "description": "Whether the client may use token exchange (RFC 8693) to act as a user rather than on behalf of one." }, "userinfo_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s UserInfo responses. Null returns plain JSON." }, "userinfo_encrypted_response_alg": { "type": [ "string", "null" ], "description": "The key-management algorithm that encrypts this client’s UserInfo responses, or null." }, "userinfo_encrypted_response_enc": { "type": [ "string", "null" ], "description": "The content-encryption algorithm for encrypted UserInfo responses, or null." }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The certificate subject a client using `tls_client_auth` must present, or null." }, "client_uri": { "type": [ "string", "null" ], "description": "A web page about the client application, shown to users." }, "policy_uri": { "type": [ "string", "null" ], "description": "The client privacy policy page, shown to users." }, "tos_uri": { "type": [ "string", "null" ], "description": "The client terms of service page, shown to users." }, "id_token_signed_response_alg": { "type": [ "string", "null" ], "description": "The algorithm that signs this client’s ID tokens. Null uses the tenant’s default." }, "default_max_age": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The longest age in seconds a sign-in may have before the user must sign in again, when the request does not say. Null sets none." }, "require_auth_time": { "type": "boolean", "description": "Whether ID tokens always carry the `auth_time` claim." }, "previous_secret_expires_at": { "type": [ "string", "null" ], "description": "When the secret that a rotation replaced stops authenticating, or null when no rotation kept one. The secret itself is never shown." }, "builtin_admin": { "type": "boolean", "description": "True for the tenant’s built-in admin console client, which cannot be deleted and is limited in what can be amended." }, "service_subject_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The service account a confidential client authenticates as, or null when it has none." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The scopes assigned to the client and whether each is `default` (always requested) or `optional` (only when asked for)." }, "service_account_admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } }, "client_secret": { "type": "string", "description": "The new secret. Shown only in this response." } }, "required": [ "id", "client_id", "name", "description", "type", "enabled", "full_scope_allowed", "registration_origin", "created_at", "redirect_uris", "grant_types", "token_endpoint_auth_method", "audiences", "access_token_ttl_seconds", "id_token_ttl_seconds", "refresh_token_ttl_seconds", "client_credentials_scopes", "web_origins", "post_logout_redirect_uris", "jwks", "jwks_uri", "frontchannel_logout_uri", "backchannel_logout_uri", "frontchannel_logout_session_required", "backchannel_logout_session_required", "consent_required", "token_exchange_impersonation_allowed", "userinfo_signed_response_alg", "userinfo_encrypted_response_alg", "userinfo_encrypted_response_enc", "tls_client_auth_subject_dn", "client_uri", "policy_uri", "tos_uri", "id_token_signed_response_alg", "default_max_age", "require_auth_time", "previous_secret_expires_at", "builtin_admin", "service_subject_id", "scopes", "service_account_admin_reach", "client_secret" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/logout-deliveries": { "get": { "summary": "Requires the \"manage-clients\" capability.", "description": "The Back-Channel Logout Tokens queued for the client, most recent first: `pending`, `delivered`, or `failed` once every attempt is spent, with the last error. Never the token itself.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The delivery’s identifier." }, "session_id": { "type": "string", "description": "The session whose end the token reports." }, "endpoint": { "type": "string", "description": "The client address the token is posted to." }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ], "description": "`pending` until delivered, `delivered` once the client answered, `failed` after the attempts ran out." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times delivery was tried." }, "last_error": { "type": [ "string", "null" ], "description": "Why the last attempt failed, or null." }, "created_at": { "type": "string", "description": "When the delivery was queued." }, "next_attempt_at": { "type": "string", "description": "When the next attempt is due." }, "delivered_at": { "type": [ "string", "null" ], "description": "When the client accepted it, or null." } }, "required": [ "id", "session_id", "endpoint", "status", "attempts", "last_error", "created_at", "next_attempt_at", "delivered_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/evaluate": { "get": { "summary": "Requires the \"manage-clients\" capability.", "description": "The claims an authorization-code exchange for this client and `subject` would put in the ID token, the access token and the UserInfo response, computed by the functions issuance calls, with none of the envelope a signer adds. `scope` is resolved against the client’s assignments, as issuance resolves it; absent, the client’s default scopes. It assumes consent is granted: for a `consent_required` client a real code carries only the scopes consented to. Signs nothing. Additionally requires `view-users`, refused with `403` otherwise, since the claims are the subject’s. Audited as `client.evaluate`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "subject", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "description": "The scopes the evaluation used, space-separated." }, "id_token": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The claims the ID token would carry, or null when the scope has no `openid`." }, "access_token": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The claims the access token would carry." }, "userinfo": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The claims the UserInfo endpoint would return." } }, "required": [ "scope", "id_token", "access_token", "userinfo" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/installation": { "get": { "summary": "Requires the \"manage-clients\" capability.", "description": "What a relying party is configured with: the issuer and its discovery URL, as this request’s host names them, and the client’s own identifier, type, authentication method, URIs, grant types and default scopes. Never the secret.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issuer": { "type": "string", "description": "The issuer identifier the application must trust." }, "discovery_url": { "type": "string", "description": "The discovery document address; most client libraries need only this." }, "client_id": { "type": "string", "description": "The `client_id` to configure in the application." }, "client_type": { "type": "string", "enum": [ "public", "confidential" ], "description": "`public` or `confidential`." }, "token_endpoint_auth_method": { "type": "string", "description": "How the application authenticates at the token endpoint." }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The redirect addresses registered for the client." }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "description": "The post-logout addresses registered for the client." }, "grant_types": { "type": "array", "items": { "type": "string" }, "description": "The grants the client may use." }, "default_scope": { "type": "string", "description": "The scopes requested when the application asks for none, space-separated." } }, "required": [ "issuer", "discovery_url", "client_id", "client_type", "token_endpoint_auth_method", "redirect_uris", "post_logout_redirect_uris", "grant_types", "default_scope" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/sessions": { "get": { "summary": "Requires the \"manage-sessions\" capability.", "description": "The live sessions holding a grant through the client: `GET …/sessions?client={id}`, answering `404` for a client that does not exist.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The session’s identifier." }, "created_at": { "type": "string", "description": "When the user signed in." }, "last_active_at": { "type": "string", "description": "When the session last did anything." }, "remembered": { "type": "boolean", "description": "Whether the user chose to stay signed in, which gives the session the longer remember-me lifetimes." }, "client_ids": { "type": "array", "items": { "type": "string" }, "description": "The clients the session has signed the user in to." }, "subject_id": { "type": "string", "description": "The user the session belongs to." }, "username": { "type": [ "string", "null" ], "description": "That user’s username, or null." } }, "required": [ "id", "created_at", "last_active_at", "remembered", "client_ids", "subject_id", "username" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/clients/{id}/grants": { "delete": { "summary": "Requires the \"manage-sessions\" capability.", "description": "Revokes up to 10,000 of the grants issued through the client that nothing has revoked, whoever holds them, so no refresh token the client holds is honoured again; `remaining` says how many more are left (counted to 10,000), so a caller repeats the call until it is 0 — one call is not every grant. Ends no session. A grant whose subject holds an admin capability the caller does not is left alone and counted under `beyond_ceiling`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "beyond_ceiling": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many belong to users holding an admin capability the caller does not, which are left alone." }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many are left; repeat the call until it is 0." } }, "required": [ "revoked", "beyond_ceiling", "remaining" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/registration-tokens": { "get": { "summary": "Requires the \"manage-clients\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The token’s identifier, for revoking it. The token itself is never shown again." }, "remaining_uses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many more registrations the token allows." }, "created_at": { "type": "string", "description": "When the token was minted." }, "expires_at": { "type": "string", "description": "When the token stops working." } }, "required": [ "id", "remaining_uses", "created_at", "expires_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-clients\" capability.", "description": "Answers `token` exactly once. Nothing else this API serves ever repeats it: not a later `GET`, not an audit detail.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uses": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "How many client registrations the token allows before it is spent." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 31536000, "description": "How long the token stays valid, from 60 seconds to a year." } }, "required": [ "uses", "ttl_seconds" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The token’s identifier, for revoking it." }, "token": { "type": "string", "description": "The initial access token. Shown only in this response; give it to the registering client as a bearer token." }, "remaining_uses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many registrations it allows." }, "expires_at": { "type": "string", "description": "When it stops working." } }, "required": [ "id", "token", "remaining_uses", "expires_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/registration-tokens/{id}": { "delete": { "summary": "Requires the \"manage-clients\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles": { "get": { "summary": "Requires the \"manage-tenant\" capability, or \"view-users\".", "description": "Also readable with `view-users`, and so with `manage-users`, whose holder assigns roles and picks them from this list. Nothing else under `/roles` is.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only roles whose name starts with this." } }, { "name": "client", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "const": "tenant" }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$", "description": "The role’s name, which a token carries. It cannot be changed afterwards." }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "What the role is for." }, "client_id": { "type": "string", "description": "The internal identifier of the client to scope the role to; omit it for a tenant role." }, "default_for_new_subjects": { "type": "boolean", "description": "Give the role to every subject created from now on." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles/count": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only roles whose name starts with this." } }, { "name": "client", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "const": "tenant" }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ], "description": "Only the roles of one owner: `tenant` for the tenant’s own roles, or a client’s internal id for the roles scoped to it." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles/{id}": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles/{id}/composites": { "post": { "summary": "Requires the \"manage-tenant\" capability.", "description": "A role nests at most 200 children; one more is refused with `409`. Nests `child_role_id` under this role. Refused with `403` when the child reaches an admin capability the caller does not hold, or any admin capability at all while a default role or a default group reaches this one; `409` on a cycle, and on a parent belonging to the tenant’s built-in admin client, whose shape provisioning fixes. Answers the composites’ new `ETag`, the one `GET …/composites` answers; `If-Match` is optional, and a stale one is refused with `412`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "child_role_id": { "type": "string", "description": "The role to nest in this one. Whoever holds this role then holds it too." } }, "required": [ "child_role_id" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "The role’s direct children only, not what they in turn include. Unpaged, like `GET /groups/:id/roles`: the list is one role’s own edges, which an operator edits edge by edge, not a tenant-wide collection.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles/{id}/composites/{childId}": { "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Removes one edge; `404` when there is none. Refused with `409` when the parent belongs to the tenant’s built-in admin client, since every administrator holding it would lose the child. Answers the composites’ new `ETag`; `If-Match` is optional, and a stale one is refused with `412`. Refused with `403` when what it removes reaches an admin capability the caller does not hold. Refused with `409` (`about:blank#last-administrator`) when it would leave no enabled subject holding `tenant-admin` — `manage-tenants` in the system tenant.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "childId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/roles/{id}/default": { "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "At most 200 roles are default at once; one more is refused with `409`. Sets whether every subject created afterwards, self-registered ones included, is granted this role. `true` is refused with `403` when the role reaches any admin capability, whoever the caller is; `false` is never refused. Answers the role’s `ETag`; `If-Match` is optional, and a stale one is refused with `412`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "default": { "type": "boolean", "description": "True to give every subject created from now on this group or role, false to stop. Subjects that already exist are not changed." } }, "required": [ "default" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier, a UUID." }, "name": { "type": "string", "description": "The role’s name, which a token carries. Fixed once the role is made." }, "description": { "type": [ "string", "null" ], "description": "What the role is for, or null." }, "client_id": { "type": [ "string", "null" ], "description": "The internal identifier of the client the role is scoped to, or null for a tenant role." }, "client_key": { "type": [ "string", "null" ], "description": "The `client_id` of that client, the name it is told apart by, or null for a tenant role. A token carries a client role as this, a colon and the role’s name." }, "default_for_new_subjects": { "type": "boolean", "description": "Whether every subject created from now on is given the role. Subjects that already exist are not changed." }, "created_at": { "type": "string", "description": "When the role was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities the role hands out, however deep it nests them, as the capability ceiling judges them." } }, "required": [ "id", "name", "description", "client_id", "client_key", "default_for_new_subjects", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/groups": { "get": { "summary": "Requires the \"manage-tenant\" capability, or \"view-users\".", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only groups whose own name starts with this, at any level." } }, { "name": "parent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "const": "root" } ], "description": "Only the groups directly under the group with this id, or `root` for the groups with no parent." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at", "admin_reach" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ] }, "parent_id": { "type": [ "string", "null" ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/groups/count": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$", "description": "Only groups whose own name starts with this, at any level." } }, { "name": "parent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "const": "root" } ], "description": "Only the groups directly under the group with this id, or `root` for the groups with no parent." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/groups/{id}": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/groups/{id}/roles": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "name", "client_id", "client_key", "admin_reach" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The identifiers of every role the subject should hold. Replaces the current set." } }, "required": [ "role_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "name", "client_id", "client_key", "admin_reach" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/groups/{id}/default": { "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "default": { "type": "boolean", "description": "True to give every subject created from now on this group or role, false to stop. Subjects that already exist are not changed." } }, "required": [ "default" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The group’s identifier, a UUID." }, "name": { "type": "string", "description": "The group’s own name, unique among the groups beside it. Fixed once the group is made." }, "description": { "type": [ "string", "null" ], "description": "What the group is for, or null." }, "parent_id": { "type": [ "string", "null" ], "description": "The group this one sits under, or null for a group at the top level." }, "default_for_new_subjects": { "type": "boolean", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "When the group was created." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] }, "description": "The admin capabilities membership of the group hands out, however deep roles nest them: its own roles and those of every group above it." } }, "required": [ "id", "name", "description", "parent_id", "default_for_new_subjects", "path", "created_at", "admin_reach" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name clients request, such as `profile`." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null." }, "include_in_id_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "How every new client gets this scope: `default`, `optional`, or null for neither." }, "consent_text": { "type": [ "string", "null" ], "description": "The sentence the consent screen shows for this scope, or null to use its name." }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the scope sorts on the consent screen; lowest first." }, "created_at": { "type": "string", "description": "When the scope was created." } }, "required": [ "id", "name", "description", "include_in_id_token", "include_in_access_token", "default_client_assignment", "consent_text", "display_order", "created_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The scope name clients will request. Unique in the tenant." }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "Free text for administrators." }, "include_in_id_token": { "type": "boolean", "description": "Whether its claims appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether its claims appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "Assign it to every new client as `default` or `optional`." }, "consent_text": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^[^\\u202A-\\u202E\\u2066-\\u2069]*$" }, { "type": "null" } ], "description": "The sentence the consent screen shows for it." }, "display_order": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Where it sorts on the consent screen; lowest first." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name clients request, such as `profile`." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null." }, "include_in_id_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "How every new client gets this scope: `default`, `optional`, or null for neither." }, "consent_text": { "type": [ "string", "null" ], "description": "The sentence the consent screen shows for this scope, or null to use its name." }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the scope sorts on the consent screen; lowest first." }, "created_at": { "type": "string", "description": "When the scope was created." } }, "required": [ "id", "name", "description", "include_in_id_token", "include_in_access_token", "default_client_assignment", "consent_text", "display_order", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/count": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name clients request, such as `profile`." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null." }, "include_in_id_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "How every new client gets this scope: `default`, `optional`, or null for neither." }, "consent_text": { "type": [ "string", "null" ], "description": "The sentence the consent screen shows for this scope, or null to use its name." }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the scope sorts on the consent screen; lowest first." }, "created_at": { "type": "string", "description": "When the scope was created." } }, "required": [ "id", "name", "description", "include_in_id_token", "include_in_access_token", "default_client_assignment", "consent_text", "display_order", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Marking a scope for every new client (`default_client_assignment`) is refused with `409` once 200 are marked.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name clients request, such as `profile`." }, "description": { "type": [ "string", "null" ], "description": "Free text for administrators, or null." }, "include_in_id_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the ID token." }, "include_in_access_token": { "type": "boolean", "description": "Whether the claims this scope adds appear in the access token." }, "default_client_assignment": { "anyOf": [ { "type": "string", "enum": [ "default", "optional" ] }, { "type": "null" } ], "description": "How every new client gets this scope: `default`, `optional`, or null for neither." }, "consent_text": { "type": [ "string", "null" ], "description": "The sentence the consent screen shows for this scope, or null to use its name." }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where the scope sorts on the consent screen; lowest first." }, "created_at": { "type": "string", "description": "When the scope was created." } }, "required": [ "id", "name", "description", "include_in_id_token", "include_in_access_token", "default_client_assignment", "consent_text", "display_order", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}/impact": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "builtin": { "type": "boolean", "description": "True for a scope every tenant has, which is deleted only when `confirm` names it." }, "client_assignments": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false, "description": "How many clients carry the scope, each of which loses it on deletion." }, "role_mappings": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false, "description": "How many roles are mapped to the scope, each unmapped on deletion." } }, "required": [ "builtin", "client_assignments", "role_mappings" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/builtins": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The scope’s name." }, "present": { "type": "boolean", "description": "False when the tenant has no scope of that name, so a restore would create it." } }, "required": [ "name", "present" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/restore-builtins": { "post": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" }, "description": "The built-in scopes the call created, in order; empty when none was missing." } }, "required": [ "created" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}/roles": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "name", "client_id", "client_key", "admin_reach" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "role_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" }, "description": "The identifiers of every role the subject should hold. Replaces the current set." } }, "required": [ "role_ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The role’s identifier." }, "name": { "type": "string", "description": "The role name." }, "client_id": { "type": [ "string", "null" ], "description": "For a role scoped to a client, that client’s internal id; null for a tenant-wide role." }, "client_key": { "type": [ "string", "null" ], "description": "For a client role, the client’s `client_id`." }, "admin_reach": { "type": "array", "items": { "type": "string", "enum": [ "view-users", "manage-users", "manage-clients", "manage-tenant", "manage-keys", "manage-sessions", "view-audit", "manage-tenants" ] } } }, "required": [ "id", "name", "client_id", "client_key", "admin_reach" ], "additionalProperties": false }, "description": "Every built-in scope, in the order a new tenant is given them." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}/mappers": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "`declared` names the mappers that declare the scope: what issuance runs for it while `bound` is empty. The `ETag` covers `bound` alone.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "available": { "type": "array", "items": { "type": "string" }, "description": "Every claim mapper the server has." }, "bound": { "type": "array", "items": { "type": "string" }, "description": "The mappers the scope uses now." }, "declared": { "type": "array", "items": { "type": "string" }, "description": "The mapper names stored for the scope, including any the server no longer has." } }, "required": [ "available", "bound", "declared" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mapper_names": { "type": "array", "items": { "type": "string" }, "description": "The mappers the scope should use. Replaces the current set." } }, "required": [ "mapper_names" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "available": { "type": "array", "items": { "type": "string" }, "description": "Every claim mapper the server has." }, "bound": { "type": "array", "items": { "type": "string" }, "description": "The mappers the scope uses now." }, "declared": { "type": "array", "items": { "type": "string" }, "description": "The mapper names stored for the scope, including any the server no longer has." } }, "required": [ "available", "bound", "declared" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}/clients": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The client’s internal identifier." }, "client_id": { "type": "string", "description": "The client’s `client_id`." }, "name": { "type": "string", "description": "The client’s display name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "How the scope is assigned to it." } }, "required": [ "id", "client_id", "name", "assignment" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/scopes/{id}/clients/{clientId}": { "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "clientId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` or `optional`." } }, "required": [ "assignment" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "client_id": { "type": "string", "description": "The client’s internal identifier." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope’s identifier." }, "name": { "type": "string", "description": "The scope name." }, "assignment": { "type": "string", "enum": [ "default", "optional" ], "description": "`default` is requested for the client without being asked for, `optional` only when the request names it." } }, "required": [ "id", "name", "assignment" ], "additionalProperties": false }, "description": "The client’s scopes after the change." } }, "required": [ "client_id", "scopes" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "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).", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, { "name": "clientId", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/keys": { "get": { "summary": "Requires the \"manage-keys\" capability.", "description": "Lists status, kid, alg, created_at and not_after — never the private half.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "rotating", "retired" ], "description": "Only keys with this status." } }, { "name": "alg", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "Only keys with this algorithm." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The key’s identifier in the admin API." }, "status": { "type": "string", "enum": [ "active", "rotating", "retired" ], "description": "`active` signs new tokens, `rotating` still verifies and is published but is not used to sign, `retired` is kept only until deleted." }, "kid": { "type": "string", "description": "The key id placed in the header of tokens it signs and published in the JWKS." }, "alg": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "The signature algorithm, `RS256` or `ES256`." }, "created_at": { "type": "string", "description": "When the key was created." }, "not_after": { "type": [ "string", "null" ], "description": "When the key stops being published for verification, or null." } }, "required": [ "id", "status", "kid", "alg", "created_at", "not_after" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "post": { "summary": "Requires the \"manage-keys\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "alg": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "The algorithm of the new key. It is created `rotating`; promote it to make it the one that signs." } }, "required": [ "alg" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The key’s identifier in the admin API." }, "status": { "type": "string", "enum": [ "active", "rotating", "retired" ], "description": "`active` signs new tokens, `rotating` still verifies and is published but is not used to sign, `retired` is kept only until deleted." }, "kid": { "type": "string", "description": "The key id placed in the header of tokens it signs and published in the JWKS." }, "alg": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "The signature algorithm, `RS256` or `ES256`." }, "created_at": { "type": "string", "description": "When the key was created." }, "not_after": { "type": [ "string", "null" ], "description": "When the key stops being published for verification, or null." } }, "required": [ "id", "status", "kid", "alg", "created_at", "not_after" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/keys/{id}/promote": { "post": { "summary": "Requires the \"manage-keys\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The key’s identifier in the admin API." }, "status": { "type": "string", "enum": [ "active", "rotating", "retired" ], "description": "`active` signs new tokens, `rotating` still verifies and is published but is not used to sign, `retired` is kept only until deleted." }, "kid": { "type": "string", "description": "The key id placed in the header of tokens it signs and published in the JWKS." }, "alg": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "The signature algorithm, `RS256` or `ES256`." }, "created_at": { "type": "string", "description": "When the key was created." }, "not_after": { "type": [ "string", "null" ], "description": "When the key stops being published for verification, or null." } }, "required": [ "id", "status", "kid", "alg", "created_at", "not_after" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/keys/{id}/retire": { "post": { "summary": "Requires the \"manage-keys\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The key’s identifier in the admin API." }, "status": { "type": "string", "enum": [ "active", "rotating", "retired" ], "description": "`active` signs new tokens, `rotating` still verifies and is published but is not used to sign, `retired` is kept only until deleted." }, "kid": { "type": "string", "description": "The key id placed in the header of tokens it signs and published in the JWKS." }, "alg": { "type": "string", "enum": [ "RS256", "ES256" ], "description": "The signature algorithm, `RS256` or `ES256`." }, "created_at": { "type": "string", "description": "When the key was created." }, "not_after": { "type": [ "string", "null" ], "description": "When the key stops being published for verification, or null." } }, "required": [ "id", "status", "kid", "alg", "created_at", "not_after" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/lockouts": { "delete": { "summary": "Requires the \"manage-users\" capability.", "description": "Clears the run of failed sign-ins of up to 10,000 subjects a call, in id order, as `DELETE …/subjects/{id}/lockout` clears one; `remaining` says how many more are left (counted to 10,000), so a caller repeats the call until it is 0 — one call is not every subject. A subject holding an admin capability the caller does not keeps its count and is counted under `beyond_ceiling`.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cleared": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many subjects’ failed sign-ins were cleared." }, "beyond_ceiling": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many hold an admin capability the caller does not, and were left locked." }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many more are left; repeat the call until it is 0." } }, "required": [ "cleared", "beyond_ceiling", "remaining" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/keys/{id}": { "delete": { "summary": "Requires the \"manage-keys\" capability.", "description": "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`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "description": "A row id.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/smtp": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "`effective` names whose relay the tenant’s mail goes through: `tenant` for its own, `deployment` for the deployment’s `ODUDU_SMTP_*` sender, `none` when mail is only logged.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether the tenant has a relay of its own saved." }, "host": { "type": [ "string", "null" ], "description": "The relay’s host, or null when the tenant has none." }, "port": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The relay’s port, or null when the tenant has none." }, "from_address": { "type": [ "string", "null" ], "description": "What the From line of each message says, or null when the tenant has no relay." }, "username": { "type": [ "string", "null" ], "description": "The login the relay asks for, or null when it asks for none." }, "password_set": { "type": "boolean", "description": "Whether a password is stored. The password itself is never returned, whether the relay was just written or read in an earlier session." }, "starttls": { "type": [ "boolean", "null" ], "description": "Whether the connection must upgrade to TLS (STARTTLS), or null when the tenant has no relay." }, "effective": { "type": "string", "enum": [ "tenant", "deployment", "none" ] } }, "required": [ "configured", "host", "port", "from_address", "username", "password_set", "starttls", "effective" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Replaces the whole configuration except the password, which GET never hands back to resend: omitting `password` keeps the stored one, and `null` clears it. A kept password stays with the relay it was entered for: omitting it while `host`, `port` or `username` changes is refused with `400` naming `password`. Answers an `ETag`, as GET does; `If-Match` is optional, and a stale one is refused with `412`.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "description": "The relay’s host." }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "description": "The relay’s port, a whole number from 1 to 65535." }, "from_address": { "type": "string", "minLength": 1, "description": "What the From line of each message says." }, "username": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "The login the relay asks for. Omit it or send null when it asks for none." }, "password": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "The password to store. Omitted, the stored one is kept while the host, port and username are unchanged; null clears it." }, "starttls": { "type": "boolean", "description": "Whether the connection must upgrade to TLS (STARTTLS). Required while a username or password is set." } }, "required": [ "host", "port", "from_address" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether the tenant has a relay of its own saved." }, "host": { "type": [ "string", "null" ], "description": "The relay’s host, or null when the tenant has none." }, "port": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The relay’s port, or null when the tenant has none." }, "from_address": { "type": [ "string", "null" ], "description": "What the From line of each message says, or null when the tenant has no relay." }, "username": { "type": [ "string", "null" ], "description": "The login the relay asks for, or null when it asks for none." }, "password_set": { "type": "boolean", "description": "Whether a password is stored. The password itself is never returned, whether the relay was just written or read in an earlier session." }, "starttls": { "type": [ "boolean", "null" ], "description": "Whether the connection must upgrade to TLS (STARTTLS), or null when the tenant has no relay." }, "effective": { "type": "string", "enum": [ "tenant", "deployment", "none" ] } }, "required": [ "configured", "host", "port", "from_address", "username", "password_set", "starttls", "effective" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Removes the tenant’s own relay, sending its mail back to the deployment’s own sender. 404 when the tenant has no SMTP configuration.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/smtp/test": { "post": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Sends one message synchronously and reports the transport’s own failure as a 502, rather than the tenant discovering a bad configuration only when a user’s verification mail silently fails. 400 when the tenant has no SMTP configuration.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "description": "The address to send the test message to." } }, "required": [ "to" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sent": { "type": "boolean", "description": "True when the relay accepted the message. A relay that refuses it answers 502 instead." } }, "required": [ "sent" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/mail": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "The tenant’s outgoing mail, most recent first: `queued`, `retrying`, `sent`, or `failed` once every attempt is spent, with its attempts and the relay’s last error. Never the body, which carries a sign-in link. The recipient is masked, wherever it appears, unless the caller also holds `view-users`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "retrying", "sent", "failed" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The message’s identifier, a UUID." }, "to": { "type": "string", "description": "The recipient’s address. Masked, with `to_masked` true, unless the caller may read subjects." }, "to_masked": { "type": "boolean", "description": "True when `to` is masked because the caller may not read subjects." }, "subject": { "type": "string", "description": "The message’s subject line. Its body is never returned, because it carries a link that signs somebody in." }, "status": { "type": "string", "enum": [ "queued", "retrying", "sent", "failed" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "last_error": { "type": [ "string", "null" ], "description": "What the last failed attempt answered, or null if none has failed." }, "created_at": { "type": "string", "description": "When the message was queued." }, "next_attempt_at": { "type": "string", "description": "When the sender will try it next." }, "sent_at": { "type": [ "string", "null" ], "description": "When it was delivered, or null if it has not been." } }, "required": [ "id", "to", "to_masked", "subject", "status", "attempts", "last_error", "created_at", "next_attempt_at", "sent_at" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/flow/executions": { "get": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Answers the steps in order, and `available`: every authenticator name a step may name, from the registry a login dispatches through. The `ETag` covers the steps alone.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The step’s position, counted from 0." }, "authenticator": { "type": "string", "description": "The sign-in step this entry runs, one of `available`." }, "requirement": { "type": "string", "enum": [ "required", "alternative", "conditional", "disabled" ], "description": "`required` always runs, `alternative` is one of several of which one suffices, `conditional` runs only when it applies to the user, `disabled` is skipped." } }, "required": [ "index", "authenticator", "requirement" ], "additionalProperties": false }, "description": "The tenant’s sign-in flow, in the order the steps run." }, "available": { "type": "array", "items": { "type": "string" }, "description": "Every authenticator a step may name." } }, "required": [ "items", "available" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } }, "put": { "summary": "Requires the \"manage-tenant\" capability.", "description": "Refused with 400, each of its own type: an empty list (`about:blank#flow-empty`), a list where every step is disabled (`#flow-no-enabled-step`), a list nothing in which can start a login (`#flow-no-first-challenge`), an authenticator name the registry does not resolve (`#flow-unknown-authenticator`), or the same authenticator named twice (`#flow-duplicate-authenticator`); the last two carry `errors[]` naming the step. 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.", "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "authenticator": { "type": "string", "minLength": 1, "description": "The sign-in step to run." }, "requirement": { "type": "string", "enum": [ "required", "alternative", "conditional", "disabled" ], "description": "`required`, `alternative`, `conditional` or `disabled`." } }, "required": [ "authenticator", "requirement" ], "additionalProperties": false } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The step’s position, counted from 0." }, "authenticator": { "type": "string", "description": "The sign-in step this entry runs, one of `available`." }, "requirement": { "type": "string", "enum": [ "required", "alternative", "conditional", "disabled" ], "description": "`required` always runs, `alternative` is one of several of which one suffices, `conditional` runs only when it applies to the user, `disabled` is skipped." } }, "required": [ "index", "authenticator", "requirement" ], "additionalProperties": false }, "description": "The tenant’s sign-in flow, in the order the steps run." }, "available": { "type": "array", "items": { "type": "string" }, "description": "Every authenticator a step may name." } }, "required": [ "items", "available" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/audit": { "get": { "summary": "Requires the \"view-audit\" capability.", "description": "Every read here runs under a five second statement timeout. Two filters whose rows are each common but that few rows share (an action and an actor, say) make Postgres read all of the cheaper one, so past the bound the read is refused with `400` of type `about:blank#audit-query-too-broad`: narrow it with `from` and `to`, which lead the index, or drop a filter. `from` and `to` are instants from 1970 to 9999, refused with `400` otherwise. Newest first, by an opaque cursor bound to the filters it was issued under.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The `next` value of the previous page, to continue after it." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many items to return. A value over 200 is treated as 200; the default is 50." } }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "admin_mutation", "admin_access", "authentication", "session", "token", "credential" ], "description": "Only events of this type." } }, { "name": "actor_subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only events done by this subject." } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this kind of resource, such as `client`." } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this resource; needs `resource_type`." } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events with this action, such as `client.create`." } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "allowed", "refused", "failed" ], "description": "Only events with this outcome." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events at or after this instant." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events before this instant." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The event’s identifier." }, "occurred_at": { "type": "string", "description": "When it happened." }, "event_type": { "type": "string", "description": "The kind of event: `admin_mutation`, `admin_access`, `authentication`, `session`, `token` or `credential`." }, "action": { "type": "string", "description": "What happened, such as `client.create` or `login.password`." }, "outcome": { "type": "string", "enum": [ "allowed", "refused", "failed" ], "description": "`allowed`, `refused` or `failed`." }, "actor_tenant_id": { "type": [ "string", "null" ], "description": "The tenant of whoever did it, or null." }, "actor_subject_id": { "type": [ "string", "null" ], "description": "The subject who did it, or null." }, "actor_client_id": { "type": [ "string", "null" ], "description": "The client it was done through, or null." }, "actor_name": { "type": [ "string", "null" ], "description": "The actor’s username, or null." }, "actor_origin": { "anyOf": [ { "type": "string", "enum": [ "tenant", "system", "other-tenant" ] }, { "type": "null" } ], "description": "Where the actor comes from: this `tenant`, the `system` tenant, or `other-tenant`." }, "resource_type": { "type": [ "string", "null" ], "description": "The kind of thing acted on, or null." }, "resource_id": { "type": [ "string", "null" ], "description": "The thing acted on, or null." }, "request_id": { "type": [ "string", "null" ], "description": "The `x-request-id` of the request, to correlate with logs." }, "ip": { "type": [ "string", "null" ], "description": "The address the server saw the request come from." }, "detail": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Extra facts about the event. Never a secret, a token or a password." } }, "required": [ "id", "occurred_at", "event_type", "action", "outcome", "actor_tenant_id", "actor_subject_id", "actor_client_id", "actor_name", "actor_origin", "resource_type", "resource_id", "request_id", "ip", "detail" ], "additionalProperties": false }, "description": "The entries of this answer." }, "next": { "type": "string", "description": "An opaque cursor for the next page; absent on the last page." } }, "required": [ "items" ], "additionalProperties": false, "examples": [ { "items": [ { "id": "0192f5c4-1d4e-7a3b-9c11-5a2f0e6b7c01", "occurred_at": "2026-10-19T09:30:00.000Z", "event_type": "admin_mutation", "action": "client.create", "outcome": "allowed", "actor_tenant_id": "0192f5c4-0000-7000-8000-000000000001", "actor_subject_id": "0192f5c4-0000-7000-8000-000000000002", "actor_client_id": "0192f5c4-0000-7000-8000-000000000003", "actor_name": "ada", "actor_origin": "tenant", "resource_type": "client", "resource_id": "0192f5c4-0000-7000-8000-000000000004", "request_id": "0192f5c4-0000-7000-8000-000000000005", "ip": "203.0.113.7", "detail": {} } ] } ] } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/audit/count": { "get": { "summary": "Requires the \"view-audit\" capability.", "description": "Every read here runs under a five second statement timeout. Two filters whose rows are each common but that few rows share (an action and an actor, say) make Postgres read all of the cheaper one, so past the bound the read is refused with `400` of type `about:blank#audit-query-too-broad`: narrow it with `from` and `to`, which lead the index, or drop a filter. `from` and `to` are instants from 1970 to 9999, refused with `400` otherwise.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "admin_mutation", "admin_access", "authentication", "session", "token", "credential" ], "description": "Only events of this type." } }, { "name": "actor_subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only events done by this subject." } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this kind of resource, such as `client`." } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this resource; needs `resource_type`." } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events with this action, such as `client.create`." } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "allowed", "refused", "failed" ], "description": "Only events with this outcome." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events at or after this instant." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events before this instant." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many items match, up to a cap." }, "capped": { "type": "boolean", "description": "True when more match than `count` says, because counting stops at the cap." } }, "required": [ "count", "capped" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } }, "/admin/tenants/{tenant}/audit/export": { "get": { "summary": "Requires the \"view-audit\" capability.", "description": "Every read here runs under a five second statement timeout. Two filters whose rows are each common but that few rows share (an action and an actor, say) make Postgres read all of the cheaper one, so past the bound the read is refused with `400` of type `about:blank#audit-query-too-broad`: narrow it with `from` and `to`, which lead the index, or drop a filter. `from` and `to` are instants from 1970 to 9999, refused with `400` otherwise. Every row the same filters list, newest first, one JSON object per line, built in full before it is sent rather than streamed. Refused whole with `413` past 10,000 rows rather than cut short. Audited as `audit.export`.", "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "admin_mutation", "admin_access", "authentication", "session", "token", "credential" ], "description": "Only events of this type." } }, { "name": "actor_subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Only events done by this subject." } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this kind of resource, such as `client`." } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events on this resource; needs `resource_type`." } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Only events with this action, such as `client.create`." } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "allowed", "refused", "failed" ], "description": "Only events with this outcome." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events at or after this instant." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Only events before this instant." } } ], "responses": { "200": { "description": "OK", "content": { "application/x-ndjson": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The event’s identifier." }, "occurred_at": { "type": "string", "description": "When it happened." }, "event_type": { "type": "string", "description": "The kind of event: `admin_mutation`, `admin_access`, `authentication`, `session`, `token` or `credential`." }, "action": { "type": "string", "description": "What happened, such as `client.create` or `login.password`." }, "outcome": { "type": "string", "enum": [ "allowed", "refused", "failed" ], "description": "`allowed`, `refused` or `failed`." }, "actor_tenant_id": { "type": [ "string", "null" ], "description": "The tenant of whoever did it, or null." }, "actor_subject_id": { "type": [ "string", "null" ], "description": "The subject who did it, or null." }, "actor_client_id": { "type": [ "string", "null" ], "description": "The client it was done through, or null." }, "actor_name": { "type": [ "string", "null" ], "description": "The actor’s username, or null." }, "actor_origin": { "anyOf": [ { "type": "string", "enum": [ "tenant", "system", "other-tenant" ] }, { "type": "null" } ], "description": "Where the actor comes from: this `tenant`, the `system` tenant, or `other-tenant`." }, "resource_type": { "type": [ "string", "null" ], "description": "The kind of thing acted on, or null." }, "resource_id": { "type": [ "string", "null" ], "description": "The thing acted on, or null." }, "request_id": { "type": [ "string", "null" ], "description": "The `x-request-id` of the request, to correlate with logs." }, "ip": { "type": [ "string", "null" ], "description": "The address the server saw the request come from." }, "detail": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Extra facts about the event. Never a secret, a token or a password." } }, "required": [ "id", "occurred_at", "event_type", "action", "outcome", "actor_tenant_id", "actor_subject_id", "actor_client_id", "actor_name", "actor_origin", "resource_type", "resource_id", "request_id", "ip", "detail" ], "additionalProperties": false } } } }, "401": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }, "403": { "description": "RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } } } } } }, "components": { "parameters": { "tenant": { "name": "tenant", "in": "path", "required": true, "description": "The tenant being administered, addressed by name.", "schema": { "type": "string" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "An access token whose \"aud\" claim names urn:odudu:params:admin-api. A token minted for another audience, including the protocol surface itself, is refused with 401." } }, "schemas": { "ProblemDetails": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "instance": { "type": "string" }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "instance" ], "additionalProperties": false } } } }