{ "openapi": "3.1.0", "info": { "title": "rIDM Admin API", "description": "Administration API of rIDM, plus the self-service account API. Admin operations need a bearer access token carrying the `urn:ridm:admin` audience; permissions are `ridm::`. Account operations (`/t/{slug}/account/...`) need a token of that tenant carrying the `urn:ridm:account` audience and act on its subject only. Errors are RFC 9457 problem documents.", "license": { "name": "MIT" }, "version": "0.4.1" }, "paths": { "/admin/audit": { "get": { "tags": [ "audit" ], "operationId": "audit_global_list", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "impersonator_id", "in": "query", "description": "Rows an administrator caused while impersonating someone.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AuditEvent" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/audit/export": { "get": { "tags": [ "audit" ], "operationId": "audit_global_export", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "impersonator_id", "in": "query", "description": "Rows an administrator caused while impersonating someone.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "json (default) or csv", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Streamed file" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/audit/verify": { "get": { "tags": [ "audit" ], "operationId": "audit_global_verify", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/download-tickets": { "post": { "tags": [ "downloads" ], "summary": "A single-use URL for one of the exports, so a browser can download it\nwith its own download manager (streamed to disk) instead of holding it in\nmemory. The caller must hold what the export itself requires.", "operationId": "downloads_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewDownloadTicket" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadTicket" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/master-key": { "get": { "tags": [ "keys" ], "summary": "Which master-key generation every encrypted row is under. Spans all\ntenants, so global administrators only.", "operationId": "keys_master_status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterStatus" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/master-key/generations": { "post": { "tags": [ "keys" ], "summary": "Have the key custody backend (`KEY_WRAPPER`) wrap a new master-key\ngeneration and make it current. 409 when the master key comes from the\nenvironment, whose generations are rolled out by changing `MASTER_KEY`.", "operationId": "keys_master_new_generation", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewGeneration" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "No key custody backend is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/master-key/rotate": { "post": { "tags": [ "keys" ], "summary": "Re-encrypt every row still under an older generation with the current\nmaster key (the new key itself comes from the environment or the key\ncustody backend).", "operationId": "keys_master_rotate", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationReport" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/me": { "get": { "tags": [ "auth" ], "summary": "Who the caller is and what they may do; the admin UI reads this after login.", "operationId": "auth_me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not an administrator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/permissions": { "get": { "tags": [ "auth" ], "summary": "The permission catalogue and built-in roles (for role editors and docs).", "operationId": "auth_permissions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionModel" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Not an administrator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/regions": { "get": { "tags": [ "tenants" ], "summary": "The databases a new tenant can be placed in, home first. Only the home\ndatabase when the deployment has no `DATA_REGIONS`.", "operationId": "tenants_regions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants": { "get": { "tags": [ "tenants" ], "summary": "Global administrators see every tenant; tenant-scoped ones see their own.", "operationId": "tenants_list", "parameters": [ { "name": "search", "in": "query", "description": "Case-insensitive prefix of the slug or display name.", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Tenant" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "tenants" ], "operationId": "tenants_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewTenant" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}": { "get": { "tags": [ "tenants" ], "operationId": "tenants_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "tenants" ], "operationId": "tenants_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "tenants" ], "operationId": "tenants_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/audit": { "get": { "tags": [ "audit" ], "summary": "`?from=&to=&name=&actor_id=&subject_id=&impersonator_id=&user_id=&cursor=&limit=`; `name`\nmatches exactly, or as a prefix when it ends with `.` or `*`.", "operationId": "audit_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "impersonator_id", "in": "query", "description": "Rows an administrator caused while impersonating someone.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AuditEvent" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/audit/export": { "get": { "tags": [ "audit" ], "summary": "Oldest first, streamed, with the chain hashes so the file can be verified offline.", "operationId": "audit_export", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "impersonator_id", "in": "query", "description": "Rows an administrator caused while impersonating someone.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "json (default) or csv", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Streamed file" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/audit/verify": { "get": { "tags": [ "audit" ], "operationId": "audit_verify", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/captcha": { "get": { "tags": [ "tenants" ], "operationId": "tenants_captcha_get", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptchaView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "tenants" ], "operationId": "tenants_captcha_put", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptchaConfig" } } }, "required": true }, "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "tenants" ], "operationId": "tenants_captcha_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/claim-mappers": { "get": { "tags": [ "mappers" ], "operationId": "mappers_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only mappers bound to this client.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_wide", "in": "query", "description": "Only tenant-wide mappers.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimMapperRow" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "mappers" ], "summary": "Body: `{name, client_id?, config}` where `config` is `{type, ..., include_in}`.", "operationId": "mappers_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewClaimMapper" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimMapperRow" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/claim-mappers/{mapper}": { "get": { "tags": [ "mappers" ], "operationId": "mappers_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "mapper", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimMapperRow" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "mappers" ], "operationId": "mappers_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "mapper", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "mappers" ], "summary": "`config` replaces the whole document (mapper types differ too much to merge).", "operationId": "mappers_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "mapper", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimMapperUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimMapperRow" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients": { "get": { "tags": [ "clients" ], "operationId": "clients_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Order: `created` (default), `name` or `type`.", "required": false, "schema": { "type": "string", "description": "What the clients list can be sorted by (the console's column headers).", "enum": [ "created", "name", "type" ] } }, { "name": "dir", "in": "query", "description": "`asc` (default) or `desc`.", "required": false, "schema": { "type": "string", "description": "Which way a sorted list runs.", "enum": [ "asc", "desc" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ClientView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "clients" ], "operationId": "clients_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewClient" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients/{client}": { "get": { "tags": [ "clients" ], "operationId": "clients_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "clients" ], "operationId": "clients_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "clients" ], "summary": "Merge patch over the client's metadata document (every field a `POST`\naccepts): send only what changed; `null` clears an optional field or\nresets a defaulted one to its type-driven default. `status` may be sent\nalongside. Switching to a secret-based auth method mints a secret that is\nreturned once in `client_secret`.", "operationId": "clients_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "JSON merge patch over the client metadata, plus `status`", "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients/{client}/registration-token": { "post": { "tags": [ "clients" ], "summary": "Issue (replacing any previous one) the RFC 7592 registration access token\nso the client's owner can manage its metadata without admin access.", "operationId": "clients_registration_token", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationTokenView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients/{client}/secrets": { "post": { "tags": [ "clients" ], "summary": "Generate a new secret (first one, or a rotation with a grace window for\nthe previous secret). The secret is in the response and nowhere else.", "operationId": "clients_rotate_secret", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients/{client}/secrets/{secret_id}": { "delete": { "tags": [ "clients" ], "operationId": "clients_revoke_secret", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "secret_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/clients/{client}/service-account": { "put": { "tags": [ "clients" ], "summary": "Create (or return) the user the client acts as under `client_credentials`.", "operationId": "clients_enable_service_account", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "clients" ], "operationId": "clients_disable_service_account", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/dcr/initial-access-tokens": { "get": { "tags": [ "clients" ], "operationId": "clients_list_tokens", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InitialAccessToken" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "clients" ], "summary": "The token is returned once, in this response. `expires_in_secs` and\n`max_uses` are optional; without them the token neither expires nor runs\nout.", "operationId": "clients_issue_token", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInitialAccessToken" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedInitialAccessToken" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/dcr/initial-access-tokens/{token}": { "delete": { "tags": [ "clients" ], "operationId": "clients_revoke_token", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "description": "Token id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/export": { "get": { "tags": [ "tenant_config" ], "summary": "Deterministic JSON (sorted keys and collections, natural keys, no secrets).", "operationId": "tenant_config_export", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfig" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups": { "get": { "tags": [ "groups" ], "summary": "Flat list with `parent_id`; the UI builds the tree.", "operationId": "groups_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "groups" ], "operationId": "groups_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewGroup" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups/{group}": { "get": { "tags": [ "groups" ], "operationId": "groups_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupDetail" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "groups" ], "operationId": "groups_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "groups" ], "summary": "`parent_id: null` moves the group to the top level.", "operationId": "groups_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups/{group}/members": { "get": { "tags": [ "groups" ], "operationId": "groups_members", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Only members whose username or email starts with this.", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Member" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups/{group}/members/{user_id}": { "put": { "tags": [ "groups" ], "operationId": "groups_add_member", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "groups" ], "operationId": "groups_remove_member", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups/{group}/roles": { "get": { "tags": [ "groups" ], "operationId": "groups_group_roles", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/groups/{group}/roles/{role_id}": { "put": { "tags": [ "groups" ], "summary": "Every member (and members of descendant groups) gains the role.", "operationId": "groups_assign_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "groups" ], "operationId": "groups_unassign_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers": { "get": { "tags": [ "identity_providers" ], "operationId": "identity_providers_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProviderView" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "identity_providers" ], "summary": "A `preset` fills in the protocol, endpoints, scopes and mappers; an OIDC\nprovider's endpoints are discovered from its `issuer` when left out.", "operationId": "identity_providers_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewIdentityProvider" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Alias in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The issuer could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/discover": { "post": { "tags": [ "identity_providers" ], "summary": "Fetch an issuer's OpenID discovery document (to preview the endpoints).", "operationId": "identity_providers_discover", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } }, "400": { "description": "Not an issuer, or its document is unusable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The issuer could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/kerberos-keytab": { "post": { "tags": [ "identity_providers" ], "summary": "Read a keytab without storing it: its entries (never a key) and the\nservices rIDM could accept tickets for with it.", "operationId": "identity_providers_kerberos_keytab", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeytabBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeytabReport" } } } }, "400": { "description": "Not a keytab", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/presets": { "get": { "tags": [ "identity_providers" ], "operationId": "identity_providers_presets", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Preset" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/saml-metadata": { "post": { "tags": [ "identity_providers" ], "summary": "Read an IdP's SAML metadata into the settings of a new `saml`\nprovider, for the administrator to review before creating it. Nothing\nis stored.", "operationId": "identity_providers_saml_metadata", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlMetadataBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlUpstreamSettings" } } } }, "400": { "description": "Not usable IdP metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The metadata URL could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/{idp}": { "get": { "tags": [ "identity_providers" ], "operationId": "identity_providers_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "identity_providers" ], "summary": "Deleting a provider drops the identities linked through it; the users\nkeep their accounts.", "operationId": "identity_providers_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "identity_providers" ], "summary": "A merge patch; `client_secret: null` clears the secret. A new `issuer`\nre-discovers the endpoints unless the patch names them.", "operationId": "identity_providers_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Alias in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/{idp}/ldap/sync": { "post": { "tags": [ "identity_providers" ], "summary": "Sync a directory's users and groups now, as the periodic job does.", "operationId": "identity_providers_ldap_sync", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LdapSyncBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LdapSyncStats" } } } }, "400": { "description": "Not an LDAP provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A sync of this directory is already running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The directory could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/{idp}/ldap/test": { "post": { "tags": [ "identity_providers" ], "summary": "Connect to a directory as its service account and read a few users\n(and groups): what a sign-in and a sync would see. Nothing is stored.", "operationId": "identity_providers_ldap_test", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What the test found; `error` says what failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestReport" } } } }, "400": { "description": "Not an LDAP provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/identity-providers/{idp}/saml/refresh": { "post": { "tags": [ "identity_providers" ], "summary": "Re-read a SAML provider's metadata URL now, as the daily job does.", "operationId": "identity_providers_saml_refresh", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp", "in": "path", "description": "Row id or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProviderView" } } } }, "400": { "description": "Not a SAML provider with a metadata URL, or its metadata is unusable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The metadata URL could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/import": { "post": { "tags": [ "tenant_config" ], "summary": "`?dry_run=true` returns the plan (creates, updates with field diffs, and\nwith `prune` deletes), with `errors` listing roles and groups whose grants\nthe caller could not make (applying would refuse them the same way). Without it the plan is applied; the report lists\nwhat was applied, any per-item errors, and the secrets of clients and\nwebhooks the import created (shown once). Applying the same document\nagain yields an empty plan.", "operationId": "tenant_config_import", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Plan only.", "required": false, "schema": { "type": "boolean" } }, { "name": "prune", "in": "query", "description": "Also delete configuration the document does not mention.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantConfig" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyReport" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/invitations": { "get": { "tags": [ "invitations" ], "operationId": "invitations_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "open_only", "in": "query", "description": "Only invitations that can still be accepted.", "required": false, "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "invitations" ], "summary": "Emails the invitee; roles and groups are granted on acceptance, so they\nare checked against the caller's own admin permissions here.", "operationId": "invitations_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInvitation" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/invitations/{invitation}": { "get": { "tags": [ "invitations" ], "operationId": "invitations_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "invitations" ], "operationId": "invitations_revoke", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/invitations/{invitation}/resend": { "post": { "tags": [ "invitations" ], "summary": "New token and expiry, emailed again; the previous link stops working.", "operationId": "invitations_resend", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/ip-rules": { "get": { "tags": [ "ip_rules" ], "operationId": "ip_rules_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only rules bound to this client.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_wide", "in": "query", "description": "Only tenant-wide rules.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IpRule" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "ip_rules" ], "summary": "`{cidr, action?: allow|deny (default deny), client_id?, description?}`.", "operationId": "ip_rules_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewIpRule" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRule" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/ip-rules/{rule}": { "get": { "tags": [ "ip_rules" ], "operationId": "ip_rules_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rule", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRule" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "ip_rules" ], "operationId": "ip_rules_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rule", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "ip_rules" ], "operationId": "ip_rules_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rule", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRuleUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRule" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys": { "get": { "tags": [ "keys" ], "operationId": "keys_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Lifecycle: pending (published, not yet signing) → active (signing) →\nretiring (published for verification only) → revoked (unpublished).", "enum": [ "pending", "active", "retiring", "revoked" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SigningKey" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "keys" ], "operationId": "keys_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKey" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys/rotate": { "post": { "tags": [ "keys" ], "summary": "New key with the tenant's default algorithm, active at once; the previous\nactive key retires with the policy's overlap.", "operationId": "keys_rotate", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys/{key}": { "get": { "tags": [ "keys" ], "operationId": "keys_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys/{key}/activate": { "post": { "tags": [ "keys" ], "operationId": "keys_activate", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys/{key}/retire": { "post": { "tags": [ "keys" ], "operationId": "keys_retire", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/keys/{key}/revoke": { "post": { "tags": [ "keys" ], "summary": "Unpublish now: tokens signed with the key stop verifying.", "operationId": "keys_revoke", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKey" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/email": { "get": { "tags": [ "messaging" ], "operationId": "messaging_email_get", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "messaging" ], "summary": "`{type: \"smtp\", host, port, username?, password?, from, security?}` or\n`{type: \"http\", url, auth_header?, from}`; an omitted secret keeps the stored one.", "operationId": "messaging_email_put", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailProviderConfig" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "messaging" ], "operationId": "messaging_email_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/email/test": { "post": { "tags": [ "messaging" ], "operationId": "messaging_email_test", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSend" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSendResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/log": { "get": { "tags": [ "messaging" ], "operationId": "messaging_log", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "sending", "sent", "dead" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/log/{message}/redeliver": { "post": { "tags": [ "messaging" ], "summary": "Put a dead message back in the queue.", "operationId": "messaging_redeliver", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "message", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/sms": { "get": { "tags": [ "messaging" ], "operationId": "messaging_sms_get", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "messaging" ], "operationId": "messaging_sms_put", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsProviderConfig" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "messaging" ], "operationId": "messaging_sms_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSettings" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/sms/test": { "post": { "tags": [ "messaging" ], "operationId": "messaging_sms_test", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSend" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSendResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/templates": { "get": { "tags": [ "messaging" ], "operationId": "messaging_templates", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Templates" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/templates/preview": { "post": { "tags": [ "messaging" ], "summary": "Render a stored template or an unsaved draft with sample variables.", "operationId": "messaging_preview", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/messaging/templates/{channel}/{event}/{locale}": { "get": { "tags": [ "messaging" ], "operationId": "messaging_template_get", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "messaging" ], "operationId": "messaging_template_put", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "messaging" ], "operationId": "messaging_template_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/mtls/trust-anchors": { "get": { "tags": [ "mtls" ], "operationId": "mtls_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MtlsTrustAnchor" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "mtls" ], "summary": "`{name, certificate_pem}`: one CA certificate (root or intermediate).", "operationId": "mtls_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewMtlsTrustAnchor" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MtlsTrustAnchor" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already trusted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/mtls/trust-anchors/{anchor}": { "delete": { "tags": [ "mtls" ], "operationId": "mtls_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "anchor", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations": { "get": { "tags": [ "organizations" ], "operationId": "organizations_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Matches the slug or the display name.", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Organization" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "organizations" ], "operationId": "organizations_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewOrganization" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}": { "get": { "tags": [ "organizations" ], "operationId": "organizations_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDetail" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "organizations" ], "summary": "Memberships, domains and org-scoped role grants go with it. Members keep\ntheir accounts; one whose primary organization this was is left without one.", "operationId": "organizations_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "organizations" ], "operationId": "organizations_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/domains": { "get": { "tags": [ "organizations" ], "operationId": "organizations_domains", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationDomain" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "organizations" ], "summary": "The response's `verification` is the value to publish as a TXT record at\n`_ridm-challenge.`; auto-join waits for the verification.", "operationId": "organizations_add_domain", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewOrganizationDomain" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomain" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/domains/{domain_id}": { "delete": { "tags": [ "organizations" ], "summary": "Members who joined through this domain keep their membership.", "operationId": "organizations_delete_domain", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "organizations" ], "operationId": "organizations_update_domain", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomainUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomain" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/domains/{domain_id}/verify": { "post": { "tags": [ "organizations" ], "summary": "Looks for the TXT record now. 400 while it is not there, 503 when the\nserver has no resolver to ask.", "operationId": "organizations_verify_domain", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomain" } } } }, "400": { "description": "The record was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No DNS resolver", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/grantable-roles": { "get": { "tags": [ "organizations" ], "summary": "The tenant's roles as a picker for this organization's grants. An\norganization's own administrator may read them here without holding\n`ridm:roles:read` tenant-wide.", "operationId": "organizations_grantable_roles", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GrantableRole" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/groups/{group_id}/roles/{role_id}": { "put": { "tags": [ "organizations" ], "summary": "Every member of the group (and of its descendants) gains the role while\nacting in this organization.", "operationId": "organizations_assign_group_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "organizations" ], "operationId": "organizations_unassign_group_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/invitations": { "get": { "tags": [ "organizations" ], "summary": "Only this organization's invitations; the tenant's others are not shown,\nso an organization's own administrator never sees them.", "operationId": "organizations_invitations", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "open_only", "in": "query", "description": "Only invitations that can still be accepted.", "required": false, "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "organizations" ], "summary": "The invitation carries this organization: accepting it creates the account\nand the membership at once. Roles and groups are granted tenant-wide on\nacceptance, so a caller confined to the organization may not attach any —\nthey grant roles within the organization afterwards.", "operationId": "organizations_invite", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInvitation" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/invitations/{invitation}": { "delete": { "tags": [ "organizations" ], "summary": "The link stops working. An invitation of another organization is not found\nhere, whatever the caller may do elsewhere.", "operationId": "organizations_revoke_invitation", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/members": { "get": { "tags": [ "organizations" ], "operationId": "organizations_members", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "description": "Only members whose username or email starts with this.", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_Member" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/members/{user_id}": { "put": { "tags": [ "organizations" ], "summary": "The user's first organization also becomes their primary one.", "operationId": "organizations_add_member", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "organizations" ], "summary": "Any role the user held only within this organization goes with the\nmembership.", "operationId": "organizations_remove_member", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/members/{user_id}/roles/{role_id}": { "put": { "tags": [ "organizations" ], "summary": "The user gains the role while acting in this organization. The caller must\nalready hold every permission the role carries.", "operationId": "organizations_assign_user_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "organizations" ], "operationId": "organizations_unassign_user_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/organizations/{org}/roles": { "get": { "tags": [ "organizations" ], "summary": "Grants scoped to this organization: they apply to sessions acting in it and\nnowhere else. `user_id` or `group_id` names the principal.", "operationId": "organizations_role_grants", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "org", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_RoleHolder" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/profile-schema": { "get": { "tags": [ "tenants" ], "summary": "The tenant's user profile schema: declared attributes, their types,\nvalidation, who may edit them and where they surface.", "operationId": "tenants_profile_schema_get", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileSchema" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "tenants" ], "summary": "Replace the profile schema. Validated structurally (names, types,\nenum values, patterns); existing attribute values are not rewritten.", "operationId": "tenants_profile_schema_put", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileSchema" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileSchema" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/resource-servers": { "get": { "tags": [ "resource_servers" ], "operationId": "resource_servers_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceServer" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "resource_servers" ], "operationId": "resource_servers_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewResourceServer" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceServer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/resource-servers/{rs}": { "get": { "tags": [ "resource_servers" ], "operationId": "resource_servers_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceServerDetail" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "resource_servers" ], "operationId": "resource_servers_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "resource_servers" ], "operationId": "resource_servers_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceServerUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceServer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/resource-servers/{rs}/permissions": { "get": { "tags": [ "resource_servers" ], "operationId": "resource_servers_permissions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "resource_servers" ], "operationId": "resource_servers_create_permission", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPermission" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Permission" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/resource-servers/{rs}/permissions/{permission_id}": { "delete": { "tags": [ "resource_servers" ], "operationId": "resource_servers_delete_permission", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "rs", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles": { "get": { "tags": [ "roles" ], "operationId": "roles_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only this client's roles.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "realm_only", "in": "query", "description": "Only realm-wide roles (no client).", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "roles" ], "operationId": "roles_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewRole" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}": { "get": { "tags": [ "roles" ], "operationId": "roles_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDetail" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "roles" ], "operationId": "roles_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "roles" ], "operationId": "roles_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}/composites": { "get": { "tags": [ "roles" ], "operationId": "roles_composites", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}/composites/{child_id}": { "put": { "tags": [ "roles" ], "summary": "Everyone holding `role` gains `child_id`, so the child's permissions\nmust be within the caller's reach.", "operationId": "roles_add_composite", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "child_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "roles" ], "operationId": "roles_remove_composite", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "child_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}/holders": { "get": { "tags": [ "roles" ], "summary": "Users and groups the role is assigned to directly.", "operationId": "roles_holders", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_RoleHolder" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}/permissions": { "get": { "tags": [ "roles" ], "operationId": "roles_permissions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/roles/{role}/permissions/{permission_id}": { "put": { "tags": [ "roles" ], "summary": "Admin-catalogue permissions can only be granted by someone who holds them.", "operationId": "roles_grant_permission", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "roles" ], "operationId": "roles_revoke_permission", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml": { "get": { "tags": [ "saml" ], "operationId": "saml_idp", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdpView" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/keys": { "post": { "tags": [ "saml" ], "summary": "Start a rollover: a new key, listed in metadata at once but not signing.", "operationId": "saml_add_key", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlKeyView" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A pending key exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/keys/{key}": { "delete": { "tags": [ "saml" ], "summary": "Remove a pending or retiring key from metadata.", "operationId": "saml_delete_key", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The active key cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/keys/{key}/activate": { "post": { "tags": [ "saml" ], "summary": "Sign with this key from now on; the active one before it is kept in\nmetadata as `retiring` until deleted.", "operationId": "saml_activate_key", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/service-providers": { "get": { "tags": [ "saml" ], "operationId": "saml_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SamlSpView" } } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "saml" ], "operationId": "saml_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpInput" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The entity ID or client id is taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/service-providers/metadata": { "post": { "tags": [ "saml" ], "summary": "Read an SP's metadata into a registration to review; nothing is saved.", "operationId": "saml_import_metadata", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpInput" } } } }, "400": { "description": "Not usable SP metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/saml/service-providers/{sp}": { "get": { "tags": [ "saml" ], "operationId": "saml_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "sp", "in": "path", "description": "The client's row id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpView" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "saml" ], "summary": "Replace the SP's settings (the public client id and status are kept).", "operationId": "saml_replace", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "sp", "in": "path", "description": "The client's row id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpInput" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SamlSpView" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The entity ID is taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "saml" ], "operationId": "saml_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "sp", "in": "path", "description": "The client's row id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/scim/tokens": { "get": { "tags": [ "scim" ], "operationId": "scim_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimTokens" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "scim" ], "summary": "The token is returned once, in this response.", "operationId": "scim_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewScimToken" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedScimToken" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/scim/tokens/{token}": { "delete": { "tags": [ "scim" ], "operationId": "scim_revoke", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/scopes": { "get": { "tags": [ "scopes" ], "operationId": "scopes_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "scopes" ], "operationId": "scopes_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewScope" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/scopes/{scope}": { "get": { "tags": [ "scopes" ], "operationId": "scopes_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "scopes" ], "operationId": "scopes_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "scopes" ], "operationId": "scopes_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scope" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/stats": { "get": { "tags": [ "tenants" ], "summary": "Sign-ins and failures per day, live sessions, users and second-factor\nadoption, and the most authorized clients, for the dashboard.", "operationId": "tenants_tenant_stats", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "description": "Window in days ending now (default 30, at most 365).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantStats" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users": { "get": { "tags": [ "users" ], "operationId": "users_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled", "locked", "pending", "deleted" ] } }, { "name": "org_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "password_algo", "in": "query", "description": "Only accounts whose password hash is in this format (`argon2id`,\n`pbkdf2-sha512`, `bcrypt`, `md5`, ...).", "required": false, "schema": { "type": "string" } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Order: `created` (default), `username`, `email`, `status` or `last_login`.", "required": false, "schema": { "type": "string", "description": "What the users list can be sorted by (the console's column headers).", "enum": [ "created", "username", "email", "status", "last_login" ] } }, { "name": "dir", "in": "query", "description": "`asc` (default) or `desc`.", "required": false, "schema": { "type": "string", "description": "Which way a sorted list runs.", "enum": [ "asc", "desc" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_UserListItem" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "users" ], "summary": "Body: every `NewUser` field plus `password` or `temporary_password: true`.\nA temporary password is returned exactly once and must be changed at\nfirst login; an explicit password is checked against the tenant policy.", "operationId": "users_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "NewUser fields plus `password` or `temporary_password: true`", "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedUser" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/export": { "get": { "tags": [ "users" ], "summary": "`GET .../users/export?format=json|csv`: every live user, streamed page by\npage, without credentials.", "operationId": "users_export", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "Streamed file" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/import": { "post": { "tags": [ "users" ], "summary": "`POST .../users/import` with `application/json` (an array of users or\n`{\"users\": [...]}`) or `text/csv` (header row; `attr.` columns become\nprofile attributes). Rows are processed independently; the report names\nevery row that failed and why.", "operationId": "users_import", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "dry_run", "in": "query", "description": "Validate only; nothing is written.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "JSON array (or {\"users\": [...]}) as application/json, or CSV with a header row as text/csv", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImportRow" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportReport" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}": { "get": { "tags": [ "users" ], "operationId": "users_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetail" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "users" ], "summary": "Soft delete; sessions and trusted devices end at once.", "operationId": "users_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "users" ], "summary": "Partial update: absent = unchanged, `null` clears. `status` covers\nenable/disable (`active` / `disabled`); `locked` and `deleted` are set by\nthe system, use the unlock and delete routes instead.", "operationId": "users_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/audit": { "get": { "tags": [ "users" ], "summary": "Audit rows where the user is the actor or the subject (`ridm:audit:read`).", "operationId": "users_user_audit", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "subject_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "impersonator_id", "in": "query", "description": "Rows an administrator caused while impersonating someone.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AuditEvent" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/consents": { "get": { "tags": [ "users" ], "operationId": "users_user_consents", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentWithClient" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/consents/{client_id}": { "delete": { "tags": [ "users" ], "operationId": "users_revoke_consent", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/credentials": { "get": { "tags": [ "users" ], "operationId": "users_credentials", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/credentials/{credential_id}": { "delete": { "tags": [ "users" ], "summary": "Remove a factor (the user lost the device, say). The password is not a\nrow here; replace it through `PUT .../password`.", "operationId": "users_delete_credential", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/devices": { "get": { "tags": [ "users" ], "operationId": "users_devices", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrustedDevice" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "users" ], "operationId": "users_revoke_devices", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revoked" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/devices/{device_id}": { "delete": { "tags": [ "users" ], "operationId": "users_revoke_device", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/force-password-change": { "post": { "tags": [ "users" ], "summary": "Flag the account so the next login demands a new password.", "operationId": "users_force_password_change", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/groups": { "get": { "tags": [ "users" ], "operationId": "users_user_groups", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGroups" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/groups/{group_id}": { "put": { "tags": [ "users" ], "operationId": "users_join_group", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGroups" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "users" ], "operationId": "users_leave_group", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/identities": { "get": { "tags": [ "users" ], "operationId": "users_user_identities", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedIdentity" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/identities/{idp_id}": { "delete": { "tags": [ "users" ], "operationId": "users_unlink_identity", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "idp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/impersonate": { "post": { "tags": [ "users" ], "summary": "Sign in as the user: a one-time URL that opens a session as them in the\nbrowser that follows it. The tenant must allow impersonation, the user\nmust be active and hold no admin permission, and every token from the\nsession names the caller in `act`.", "operationId": "users_impersonate", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonationTicket" } } } }, "400": { "description": "No reason, or the caller themselves", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing, impersonation off, or the user is an administrator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The user is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/password": { "put": { "tags": [ "users" ], "operationId": "users_set_password", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Optional", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporaryPassword" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/pats": { "get": { "tags": [ "users" ], "operationId": "users_user_pats", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessToken" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/pats/{token_id}": { "delete": { "tags": [ "users" ], "operationId": "users_revoke_pat", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/roles": { "get": { "tags": [ "users" ], "operationId": "users_user_roles", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRoles" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/roles/{role_id}": { "put": { "tags": [ "users" ], "operationId": "users_assign_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRoles" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "users" ], "operationId": "users_unassign_role", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/sessions": { "get": { "tags": [ "users" ], "operationId": "users_list_sessions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SsoSession" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "users" ], "operationId": "users_revoke_sessions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revoked" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/sessions/{session_id}": { "delete": { "tags": [ "users" ], "operationId": "users_revoke_session", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/users/{user}/unlock": { "post": { "tags": [ "users" ], "summary": "Clear a lockout (failed-attempt counter and `locked` status).", "operationId": "users_unlock", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks": { "get": { "tags": [ "webhooks" ], "operationId": "webhooks_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "`{name, url, events, enabled?, headers?, max_attempts?}`; the signing\n`secret` is in the response and nowhere else.", "operationId": "webhooks_create", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewWebhook" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}": { "get": { "tags": [ "webhooks" ], "operationId": "webhooks_get_one", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "webhooks" ], "operationId": "webhooks_delete", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "webhooks" ], "operationId": "webhooks_update", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/deliveries": { "get": { "tags": [ "webhooks" ], "operationId": "webhooks_deliveries", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "dead" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/deliveries/redeliver-dead": { "post": { "tags": [ "webhooks" ], "operationId": "webhooks_redeliver_dead", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requeued" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/deliveries/{delivery}": { "get": { "tags": [ "webhooks" ], "operationId": "webhooks_delivery", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/deliveries/{delivery}/redeliver": { "post": { "tags": [ "webhooks" ], "summary": "Requeue and attempt at once; the returned delivery shows the outcome.", "operationId": "webhooks_redeliver", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/secret": { "post": { "tags": [ "webhooks" ], "operationId": "webhooks_rotate_secret", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/admin/tenants/{slug}/webhooks/{webhook}/test": { "post": { "tags": [ "webhooks" ], "summary": "Deliver a `webhook.test` event now and report the attempt.", "operationId": "webhooks_test", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/apps": { "get": { "tags": [ "account" ], "operationId": "account_list_apps", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentedApp" } } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/apps/{client_id}": { "delete": { "tags": [ "account" ], "summary": "Withdraw the consent and the refresh tokens the application holds; its\nnext sign-in asks again.", "operationId": "account_revoke_app", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "path", "description": "The client's row id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/backchannel-requests": { "get": { "tags": [ "account" ], "operationId": "account_list_requests", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingRequest" } } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/backchannel-requests/{id}/approve": { "post": { "tags": [ "account" ], "summary": "Approve the request: the client receives tokens for the scopes it asked\nfor, as if the user had signed in to it, and the grant is remembered as\nconsent (so it shows, and can be withdrawn, under connected apps).", "operationId": "account_approve_request", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The request's id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "An impersonated session, or a token without a live sign-in session (a personal access token), cannot approve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/backchannel-requests/{id}/deny": { "post": { "tags": [ "account" ], "summary": "Deny the request: the client's next token request is refused with\n`access_denied`.", "operationId": "account_deny_request", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The request's id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "An impersonated session cannot answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such pending request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/devices": { "get": { "tags": [ "account" ], "operationId": "account_list", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrustedDevice" } } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "account" ], "operationId": "account_revoke_all", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/devices/{device_id}": { "delete": { "tags": [ "account" ], "operationId": "account_revoke", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/email/change": { "post": { "tags": [ "account" ], "operationId": "account_change_email", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewEmail" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sent" } } } }, "400": { "description": "Invalid address or the current one (field errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Address in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "account" ], "operationId": "account_cancel_email_change", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/email/confirm": { "post": { "tags": [ "account" ], "operationId": "account_confirm_email_change", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Wrong code or nothing pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Address in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/export": { "get": { "tags": [ "account" ], "summary": "Everything held about the user as one JSON document, offered as a\ndownload. Secrets are never part of it.", "operationId": "account_export", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountExport" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/identities": { "get": { "tags": [ "account" ], "operationId": "account_list_identities", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identities" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/identities/link": { "post": { "tags": [ "account" ], "summary": "Needs a recent sign-in (with the second step once there is one).", "operationId": "account_start_link", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkStart" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/identities/{idp_id}": { "delete": { "tags": [ "account" ], "operationId": "account_unlink_identity", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "idp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/me": { "get": { "tags": [ "account" ], "operationId": "account_me", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMe" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Token of another tenant or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "account" ], "summary": "Delete the account: every session, token and trusted device ends now,\nthe username and email free up, and the record is purged after the\norganisation's retention period. Needs a recent sign-in (with the\nsecond step once there is one). Administrators cannot delete\nthemselves.", "operationId": "account_delete_me", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccount" } } }, "required": true }, "responses": { "204": { "description": "No content" }, "400": { "description": "Confirmation mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required, not allowed, or an administrator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa": { "get": { "tags": [ "account" ], "operationId": "account_status", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaStatus" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/credentials/{credential_id}": { "delete": { "tags": [ "account" ], "summary": "Remove a factor. The recovery codes go with the last one.", "operationId": "account_delete_credential", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/email/confirm": { "post": { "tags": [ "account" ], "operationId": "account_email_confirm", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolled" } } } }, "400": { "description": "Wrong code or nothing pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/email/enroll": { "post": { "tags": [ "account" ], "operationId": "account_email_enroll", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sent" } } } }, "400": { "description": "Already enrolled, disabled or no address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many codes sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/passkey/register": { "post": { "tags": [ "account" ], "operationId": "account_passkey_register", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "WebAuthn creation options", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Passkeys disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/passkey/register/finish": { "post": { "tags": [ "account" ], "operationId": "account_passkey_register_finish", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyFinishBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolled" } } } }, "400": { "description": "The passkey could not be verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/recovery-codes": { "post": { "tags": [ "account" ], "summary": "Replace the recovery codes; the new set is shown once.", "operationId": "account_recovery_codes", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodes" } } } }, "400": { "description": "No second factor enrolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/sms/confirm": { "post": { "tags": [ "account" ], "operationId": "account_sms_confirm", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolled" } } } }, "400": { "description": "Wrong code or nothing pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/sms/enroll": { "post": { "tags": [ "account" ], "operationId": "account_sms_enroll", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneBody" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sent" } } } }, "400": { "description": "Already enrolled, disabled or no number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many codes sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/totp/confirm": { "post": { "tags": [ "account" ], "operationId": "account_totp_confirm", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolled" } } } }, "400": { "description": "Wrong code or nothing pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/mfa/totp/enroll": { "post": { "tags": [ "account" ], "operationId": "account_totp_enroll", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolment" } } } }, "400": { "description": "Already enrolled or disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/organizations": { "get": { "tags": [ "account" ], "summary": "Read-only: membership is managed by an administrator, by an invitation or\nby a verified auto-join domain. To act in another one, sign in again.", "operationId": "account_list_organizations", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOrganization" } } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/password": { "get": { "tags": [ "account" ], "operationId": "account_get_password", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordStatus" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "account" ], "operationId": "account_change_password", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePassword" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChanged" } } } }, "400": { "description": "Wrong current password or policy failure (field errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/phone": { "delete": { "tags": [ "account" ], "operationId": "account_remove_phone", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "The number backs an SMS second step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No number on the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/phone/change": { "post": { "tags": [ "account" ], "operationId": "account_change_phone", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPhone" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sent" } } } }, "400": { "description": "Invalid number or the current one (field errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "account" ], "operationId": "account_cancel_phone_change", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/phone/confirm": { "post": { "tags": [ "account" ], "operationId": "account_confirm_phone_change", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Wrong code or nothing pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/profile": { "get": { "tags": [ "account" ], "operationId": "account_get_profile", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "account" ], "operationId": "account_patch_profile", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/sessions": { "get": { "tags": [ "account" ], "operationId": "account_list_sessions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSession" } } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "account" ], "operationId": "account_revoke_all_sessions", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "keep_current", "in": "query", "description": "Keep the session this request was made from.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revoked" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/sessions/{session_id}": { "delete": { "tags": [ "account" ], "operationId": "account_revoke_session", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/tokens": { "get": { "tags": [ "account" ], "operationId": "account_list_tokens", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tokens" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "account" ], "summary": "The token is in the answer once and never again.", "operationId": "account_create_token", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPersonalAccessToken" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedPersonalAccessToken" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required, or tokens are not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } }, "/t/{slug}/account/tokens/{token_id}": { "delete": { "tags": [ "account" ], "operationId": "account_revoke_token", "parameters": [ { "name": "slug", "in": "path", "description": "Tenant slug", "required": true, "schema": { "type": "string" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Recent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found or already revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "AccessTokenFormat": { "type": "string", "enum": [ "jwt", "opaque" ] }, "AccountExport": { "type": "object", "description": "Everything rIDM holds about one user, for a data-portability request.\nSecrets (password hashes, factor material, device keys) are never part\nof it.", "required": [ "exported_at", "tenant", "user", "credentials", "trusted_devices", "sessions", "consents", "personal_access_tokens", "identities", "roles", "groups", "audit_events" ], "properties": { "audit_events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" }, "description": "The user's audit trail (as actor or subject), newest first, capped." }, "consents": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentedApp" } }, "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" }, "description": "Second factors, passkeys and recovery-code sets (metadata only)." }, "exported_at": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "Groups the user belongs to, ancestors included." }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedIdentity" }, "description": "Upstream identities linked to the account." }, "personal_access_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessToken" }, "description": "Personal access tokens (metadata only)." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Effective role names." }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SsoSession" } }, "tenant": { "$ref": "#/components/schemas/ExportedTenant" }, "trusted_devices": { "type": "array", "items": { "$ref": "#/components/schemas/TrustedDevice" } }, "user": { "$ref": "#/components/schemas/User" } } }, "AccountImpersonation": { "type": "object", "required": [ "impersonator", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "When the session ends by itself." }, "impersonator": { "type": "string", "description": "The administrator's username (in their own tenant)." } } }, "AccountMe": { "type": "object", "required": [ "id", "username", "email_verified", "phone_verified", "tenant", "amr" ], "properties": { "acr": { "type": [ "string", "null" ], "description": "Authentication context class of the session (`urn:ridm:acr:mfa` after a second step)." }, "amr": { "type": "array", "items": { "type": "string" }, "description": "Methods the session was authenticated with." }, "auth_time": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sign-in behind this token happened." }, "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "impersonation": { "oneOf": [ { "$ref": "#/components/schemas/AccountImpersonation", "description": "Set when an administrator opened this session as the user. Changes\nto credentials, consent and the account's existence are refused." }, { "type": "null" } ] }, "phone": { "type": [ "string", "null" ] }, "phone_verified": { "type": "boolean" }, "tenant": { "$ref": "#/components/schemas/AccountTenant" }, "username": { "type": "string" } } }, "AccountOrganization": { "type": "object", "required": [ "id", "slug", "display_name", "primary" ], "properties": { "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "primary": { "type": "boolean", "description": "The user's primary organization." }, "slug": { "type": "string" } } }, "AccountPolicy": { "type": "object", "description": "Self-service rights of the account console.", "properties": { "deletion_retention_days": { "type": "integer", "format": "int32", "description": "Days a soft-deleted account stays recoverable before the purge job\nremoves it and everything attached to it.", "default": 30, "minimum": 0 }, "personal_token_max_days": { "type": "integer", "format": "int32", "description": "The longest a personal access token may live (and the default);\n`0` allows tokens that never expire.", "default": 365, "minimum": 0 }, "personal_tokens": { "type": "boolean", "description": "Users may mint personal access tokens.", "default": true }, "self_deletion": { "type": "boolean", "description": "Users may delete their own account (`DELETE /t/{slug}/account/me`).", "default": true } } }, "AccountSession": { "type": "object", "description": "A live browser session of the user.", "required": [ "id", "current", "auth_time", "amr", "created_at", "last_seen_at", "expires_at" ], "properties": { "acr": { "type": [ "string", "null" ] }, "amr": { "type": "array", "items": { "type": "string" } }, "auth_time": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "current": { "type": "boolean", "description": "The session this request was made from." }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "impersonated_by": { "type": [ "string", "null" ], "description": "The administrator (their username) who opened this session as the\nuser. The session's address and browser are theirs, so neither is\nshown." }, "ip": { "type": [ "string", "null" ] }, "last_seen_at": { "type": "string", "format": "date-time" }, "user_agent": { "type": [ "string", "null" ] } } }, "AccountTenant": { "type": "object", "required": [ "slug", "display_name" ], "properties": { "display_name": { "type": "string" }, "slug": { "type": "string" } } }, "AdminScope": { "type": "string", "description": "How far an administrator's permissions reach.", "enum": [ "global", "tenant" ] }, "ApplyError": { "type": "object", "required": [ "resource", "key", "error" ], "properties": { "error": { "type": "string" }, "key": { "type": "string" }, "resource": { "type": "string" } } }, "ApplyReport": { "allOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "object", "required": [ "dry_run", "applied", "errors" ], "properties": { "applied": { "type": "integer", "minimum": 0 }, "dry_run": { "type": "boolean" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApplyError" } }, "secrets": { "$ref": "#/components/schemas/Secrets" } } } ] }, "Attention": { "type": "object", "description": "What is waiting on an administrator.", "required": [ "locked_users", "open_invitations", "expiring_keys", "dead_deliveries" ], "properties": { "dead_deliveries": { "type": "integer", "format": "int64", "description": "Webhook deliveries given up on (`dead`) in the last 7 days." }, "expiring_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ExpiringKey" }, "description": "Active or retiring keys whose publication ends within 14 days." }, "locked_users": { "type": "integer", "format": "int64", "description": "Accounts locked by status or by a lockout still running." }, "oldest_invitation_at": { "type": [ "string", "null" ], "format": "date-time" }, "open_invitations": { "type": "integer", "format": "int64", "description": "Invitations neither accepted, revoked nor expired." } } }, "AttributeDef": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "default": null }, "editable_by": { "$ref": "#/components/schemas/EditableBy", "default": "user" }, "label": { "type": [ "string", "null" ], "default": null }, "multivalued": { "type": "boolean", "default": false }, "name": { "type": "string", "default": "" }, "order": { "type": "integer", "format": "int32", "description": "Position in forms.", "default": 0, "minimum": 0 }, "required": { "type": "boolean", "default": false }, "type": { "$ref": "#/components/schemas/AttributeType", "default": "string" }, "validation": { "$ref": "#/components/schemas/AttributeValidation", "default": { "max": null, "max_length": null, "min": null, "min_length": null, "pattern": null, "values": [] } }, "visible_in": { "type": "array", "items": { "$ref": "#/components/schemas/Exposure" }, "default": [] } } }, "AttributeNameFormat": { "type": "string", "description": "`NameFormat` of a released attribute.", "enum": [ "basic", "uri", "unspecified" ] }, "AttributeType": { "type": "string", "enum": [ "string", "number", "boolean", "email", "url", "phone", "date", "enum", "json" ] }, "AttributeValidation": { "type": "object", "properties": { "max": { "type": [ "number", "null" ], "format": "double", "default": null }, "max_length": { "type": [ "integer", "null" ], "format": "int32", "default": null, "minimum": 0 }, "min": { "type": [ "number", "null" ], "format": "double", "default": null }, "min_length": { "type": [ "integer", "null" ], "format": "int32", "default": null, "minimum": 0 }, "pattern": { "type": [ "string", "null" ], "description": "Anchored regular expression the string form must match.", "default": null }, "values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values for `enum`.", "default": [] } } }, "AuditEvent": { "type": "object", "description": "One audit row: a domain event as recorded, with its place in the\ntenant's hash chain.", "required": [ "id", "seq", "occurred_at", "recorded_at", "name", "actor_type", "payload", "hash" ], "properties": { "actor_id": { "type": [ "string", "null" ], "format": "uuid" }, "actor_type": { "type": "string", "description": "`user`, `client`, `admin` or `system`." }, "hash": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "impersonator_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The administrator behind the event, when it happened in a session\nthey opened as a user (impersonation)." }, "ip": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Dotted event name (`user.created`)." }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "description": "The event's `kind` document (`type` plus its fields)." }, "prev_hash": { "type": [ "string", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "seq": { "type": "integer", "format": "int64", "description": "Position in the chain (per tenant, or the global chain)." }, "subject_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The main entity the event is about (user, client, role, ...), when it has one." }, "tenant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "`None` for global (cross-tenant) events." }, "user_agent": { "type": [ "string", "null" ] } } }, "AuditPolicy": { "type": "object", "description": "Audit retention, per tenant.", "properties": { "retention_days": { "type": "integer", "format": "int32", "description": "Days to keep audit rows (0 = forever).", "default": 365, "minimum": 0 } } }, "AuthMethods": { "type": "object", "description": "Which first-factor login methods the tenant offers.", "properties": { "email_otp": { "type": "boolean", "default": false }, "magic_link": { "type": "boolean", "default": false }, "passkey": { "type": "boolean", "default": false }, "password": { "type": "boolean", "default": true }, "sms_otp": { "type": "boolean", "default": false } } }, "BackchannelDeliveryMode": { "type": "string", "description": "How a CIBA client learns the user decided (CIBA Core §5). Push is not\noffered: it puts the tokens themselves on an outbound call.", "enum": [ "poll", "ping" ] }, "Branding": { "type": "object", "description": "How the tenant looks: the sign-in pages, the account console and the admin\nconsole while it administers this tenant. The two theme colours feed the\nUI's ramp engine (`ui/src/lib/theme/ramp.ts`), which derives every shade\nfor light and dark mode from them.", "properties": { "allow_theme_switch": { "type": "boolean", "description": "People may override `mode` on their own device.", "default": true }, "background_color": { "type": [ "string", "null" ], "default": null }, "contrast_color": { "type": [ "string", "null" ], "description": "The theme's second colour, for what must read as different from the\nprimary (selection, the tenant mark). Hex; derived from the primary by\nhue rotation when `null`.", "default": null }, "custom_css": { "type": [ "string", "null" ], "default": null }, "favicon_url": { "type": [ "string", "null" ], "default": null }, "headline": { "type": [ "string", "null" ], "description": "A line for the sign-in page's brand panel (\"One sign-in for everything\nat Acme.\"). With the Signal v2 skin the page splits into the panel and\nthe form once this is set; the other skins keep the single card.", "default": null }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/BrandingLink" }, "default": [] }, "logo_url": { "type": [ "string", "null" ], "default": null }, "mode": { "$ref": "#/components/schemas/ThemeMode", "description": "Light/dark policy for every surface of the tenant.", "default": "system" }, "primary_color": { "type": [ "string", "null" ], "description": "The theme's primary colour: actions, navigation, links, focus. A hex\ncolour drives the full tonal ramp; other CSS colour literals set the\nplain accent only.", "default": null }, "skin": { "$ref": "#/components/schemas/Skin", "description": "The visual skin (Phase 15): token set and layout family.", "default": "signal-v2" }, "support_url": { "type": [ "string", "null" ], "default": null }, "tagline": { "type": [ "string", "null" ], "description": "A sentence under the headline.", "default": null } } }, "BrandingLink": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string" }, "url": { "type": "string" } } }, "BuiltInRoleDoc": { "type": "object", "required": [ "name", "description", "permissions" ], "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "CaptchaConfig": { "type": "object", "description": "CAPTCHA provider configuration. `secret` is only ever handled decrypted\ninside the process; the admin API returns it redacted.", "required": [ "provider", "site_key", "secret" ], "properties": { "provider": { "$ref": "#/components/schemas/CaptchaProvider" }, "secret": { "type": "string" }, "site_key": { "type": "string" }, "verify_url": { "type": [ "string", "null" ], "description": "Override the verification endpoint (tests, self-hosted proxies)." } } }, "CaptchaPolicy": { "type": "object", "description": "When to demand a CAPTCHA (the provider itself is configured with its\nsecret in `tenant_provider_settings`).", "properties": { "after_failures": { "type": "integer", "format": "int32", "description": "Require a challenge after this many failed attempts in a flow (0 = never).", "default": 3, "minimum": 0 }, "on_registration": { "type": "boolean", "default": true } } }, "CaptchaProvider": { "type": "string", "enum": [ "turnstile", "h_captcha" ] }, "CaptchaView": { "type": "object", "description": "CAPTCHA provider configuration with the secret redacted.", "required": [ "provider", "site_key", "secret_set" ], "properties": { "provider": { "$ref": "#/components/schemas/CaptchaProvider" }, "secret_set": { "type": "boolean", "description": "Always true when configured; the secret itself is never returned." }, "site_key": { "type": "string" }, "verify_url": { "type": [ "string", "null" ] } } }, "Change": { "type": "object", "required": [ "resource", "key", "op" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldChange" } }, "key": { "type": "string" }, "op": { "$ref": "#/components/schemas/Op" }, "resource": { "type": "string" } } }, "ChangePassword": { "type": "object", "properties": { "current_password": { "type": [ "string", "null" ], "description": "Required while the account has a password.", "default": null }, "new_password": { "type": "string", "default": "" }, "sign_out_others": { "type": "boolean", "description": "End every other session and its refresh tokens.", "default": false } }, "additionalProperties": false }, "ClaimMapperRow": { "type": "object", "description": "A stored claim mapper row; `config` is the [`crate::models::ClaimMapper`] document.", "required": [ "id", "tenant_id", "name", "config", "created_at", "updated_at" ], "properties": { "client_id": { "type": [ "string", "null" ], "format": "uuid" }, "config": {}, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ClaimMapperUpdate": { "type": "object", "description": "Partial mapper update; the client scope is immutable.", "properties": { "config": {}, "name": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "Client": { "type": "object", "required": [ "id", "tenant_id", "client_id", "name", "client_type", "token_endpoint_auth_method", "redirect_uris", "post_logout_redirect_uris", "allowed_grants", "allowed_scopes", "allowed_audiences", "access_token_format", "subject_type", "require_pkce", "require_consent", "id_token_scope_claims", "cors_origins", "dpop_bound_access_tokens", "security_profile", "require_pushed_authorization_requests", "tls_client_certificate_bound_access_tokens", "status", "created_at", "updated_at" ], "properties": { "access_token_format": { "$ref": "#/components/schemas/AccessTokenFormat" }, "access_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32" }, "allowed_audiences": { "type": "array", "items": { "type": "string" } }, "allowed_grants": { "type": "array", "items": { "type": "string" } }, "allowed_scopes": { "type": "array", "items": { "type": "string" } }, "backchannel_client_notification_endpoint": { "type": [ "string", "null" ], "description": "Where a `ping` client is told a request was decided." }, "backchannel_logout_uri": { "type": [ "string", "null" ] }, "backchannel_token_delivery_mode": { "oneOf": [ { "$ref": "#/components/schemas/BackchannelDeliveryMode", "description": "CIBA delivery mode; set exactly when the client may use the CIBA grant." }, { "type": "null" } ] }, "client_id": { "type": "string" }, "client_type": { "$ref": "#/components/schemas/ClientType" }, "client_uri": { "type": [ "string", "null" ] }, "cors_origins": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "dpop_bound_access_tokens": { "type": "boolean", "description": "Every access token must be sender-constrained with a DPoP proof\n(RFC 9449 §5.2 `dpop_bound_access_tokens`)." }, "frontchannel_logout_uri": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "id_token_encryption": { "oneOf": [ { "$ref": "#/components/schemas/IdTokenEncryptionConfig" }, { "type": "null" } ] }, "id_token_scope_claims": { "type": "boolean", "description": "Carry the claims the `profile`, `email`, `address` and `phone` scopes\nask for in the ID token as well. Off by default: with an access token\nissued, they belong at the userinfo endpoint (OIDC Core §5.4)." }, "id_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32" }, "initiate_login_uri": { "type": [ "string", "null" ] }, "jwks": {}, "jwks_uri": { "type": [ "string", "null" ] }, "logo_uri": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "policy_uri": { "type": [ "string", "null" ] }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" } }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "refresh_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32" }, "require_consent": { "type": "boolean" }, "require_pkce": { "type": "boolean" }, "require_pushed_authorization_requests": { "type": "boolean", "description": "Authorization requests must come through PAR (RFC 9126 §6); always\nso under the FAPI 2.0 profile." }, "sector_identifier_uri": { "type": [ "string", "null" ] }, "security_profile": { "$ref": "#/components/schemas/SecurityProfile" }, "service_account_user_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "$ref": "#/components/schemas/ClientStatus" }, "subject_type": { "$ref": "#/components/schemas/ClientSubjectType" }, "tenant_id": { "type": "string", "format": "uuid" }, "tls_client_auth_san_dns": { "type": [ "string", "null" ] }, "tls_client_auth_san_email": { "type": [ "string", "null" ] }, "tls_client_auth_san_ip": { "type": [ "string", "null" ] }, "tls_client_auth_san_uri": { "type": [ "string", "null" ] }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "description": "The subject a `tls_client_auth` certificate must carry: exactly one\nof these five is set for such a client (RFC 8705 §2.1.2). The DN is\nan RFC 4514 string, most specific RDN first." }, "tls_client_certificate_bound_access_tokens": { "type": "boolean", "description": "Every access token is bound to the client certificate presented at\nthe token endpoint (`cnf.x5t#S256`, RFC 8705 §3)." }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/TokenEndpointAuthMethod" }, "tos_uri": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "ClientDoc": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" }, "service_account": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/ClientStatus" } } } ], "description": "A client's metadata document: every field `POST /clients` accepts, plus\n`status` and whether it has a service account. Never a secret." }, "ClientStats": { "type": "object", "required": [ "id", "client_id", "name", "authorizations" ], "properties": { "authorizations": { "type": "integer", "format": "int64", "description": "Authorizations granted in the window." }, "client_id": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "ClientStatus": { "type": "string", "enum": [ "active", "disabled" ] }, "ClientSubjectType": { "type": "string", "enum": [ "public", "pairwise" ] }, "ClientType": { "type": "string", "enum": [ "spa", "web", "native", "machine", "device", "saml" ] }, "ClientView": { "allOf": [ { "$ref": "#/components/schemas/Client" }, { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretView" } } } } ], "description": "Client as returned to administrators: every metadata column, plus the\nsecrets' ids and validity windows (never the secrets or their hashes)." }, "Code": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } }, "additionalProperties": false }, "CodeBody": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "label": { "type": [ "string", "null" ], "description": "A name for the factor (authenticator app only)." } } }, "Consent": { "type": "object", "required": [ "tenant_id", "user_id", "client_id", "scopes", "granted_at" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "granted_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } }, "tenant_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "ConsentWithClient": { "allOf": [ { "$ref": "#/components/schemas/Consent" }, { "type": "object", "required": [ "client_name", "client" ], "properties": { "client": { "type": "string", "description": "The client's public `client_id`." }, "client_name": { "type": "string", "description": "The client's display name." }, "logo_uri": { "type": [ "string", "null" ] }, "policy_uri": { "type": [ "string", "null" ] }, "tos_uri": { "type": [ "string", "null" ] } } } ], "description": "A consent with what listings show of its client." }, "ConsentedApp": { "type": "object", "description": "An application the user granted scopes to.", "required": [ "client_id", "client", "name", "scopes", "granted_at" ], "properties": { "client": { "type": "string", "description": "The client's public `client_id`." }, "client_id": { "type": "string", "format": "uuid", "description": "The client's row id (the key for revocation)." }, "granted_at": { "type": "string", "format": "date-time" }, "logo_uri": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "policy_uri": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tos_uri": { "type": [ "string", "null" ] } } }, "Counts": { "type": "object", "description": "How many of each the tenant has (the console sidebar).", "required": [ "users", "groups", "clients", "webhooks", "keys", "idps" ], "properties": { "clients": { "type": "integer", "format": "int64" }, "groups": { "type": "integer", "format": "int64" }, "idps": { "type": "integer", "format": "int64", "description": "OIDC, SAML, LDAP and Kerberos upstream providers together." }, "keys": { "type": "integer", "format": "int64", "description": "Pending, active and retiring signing keys." }, "users": { "type": "integer", "format": "int64" }, "webhooks": { "type": "integer", "format": "int64" } } }, "CreateKey": { "type": "object", "properties": { "activate": { "type": "boolean", "description": "Publish only (`pending`) unless set, in which case the key starts\nsigning at once and the previous active key retires with overlap.", "default": false }, "alg": { "oneOf": [ { "$ref": "#/components/schemas/SigningAlg", "description": "Defaults to the tenant's key policy." }, { "type": "null" } ], "default": null }, "not_before": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest signing time (informational until activation).", "default": null }, "rsa_bits": { "type": [ "integer", "null" ], "format": "int32", "description": "2048, 3072 or 4096; defaults to the tenant's key policy.", "default": null, "minimum": 0 } }, "additionalProperties": false }, "CreatedInitialAccessToken": { "allOf": [ { "$ref": "#/components/schemas/InitialAccessToken" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } ], "description": "The token is returned once, here." }, "CreatedPersonalAccessToken": { "allOf": [ { "$ref": "#/components/schemas/PersonalAccessToken" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The bearer token, shown once." } } } ], "description": "A freshly minted token: the secret is only ever returned here." }, "CreatedScimToken": { "allOf": [ { "$ref": "#/components/schemas/ScimToken" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } ], "description": "The token is returned once, here." }, "CreatedUser": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "temporary_password": { "type": [ "string", "null" ] } } } ], "description": "Response to a create or password change that minted a temporary password." }, "Credential": { "type": "object", "description": "A user's non-password credential (MFA factors, passkeys, recovery codes),\nas listed to administrators and the user: the encrypted material stays\nin the row and is never part of this view.", "required": [ "id", "tenant_id", "user_id", "kind", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "`password`, `totp`, `webauthn`, `recovery_code`, `email_otp` or `sms_otp`." }, "label": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "Credentials": { "type": "object", "required": [ "password", "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" }, "description": "MFA factors, passkeys and recovery codes (metadata only)." }, "password": { "$ref": "#/components/schemas/PasswordSummary" } } }, "DataEncryption": { "type": "string", "description": "The block cipher for the content.", "enum": [ "aes256-gcm", "aes128-gcm", "aes256-cbc", "aes128-cbc" ] }, "DayStats": { "type": "object", "required": [ "date", "logins", "failed" ], "properties": { "date": { "type": "string", "format": "date" }, "failed": { "type": "integer", "format": "int64" }, "logins": { "type": "integer", "format": "int64" } } }, "DcrMode": { "type": "string", "enum": [ "disabled", "open", "initial_access_token" ] }, "DcrPolicy": { "type": "object", "description": "Dynamic client registration policy (RFC 7591).", "properties": { "allowed_grants": { "type": "array", "items": { "type": "string" }, "description": "Grant types a dynamically registered client may request.", "default": [] }, "mode": { "$ref": "#/components/schemas/DcrMode", "default": "disabled" }, "require_pkce": { "type": "boolean", "description": "Whether dynamically registered confidential clients must use PKCE at\n`/authorize` (public clients always must). On by default; the OpenID\nConnect basic profile registers confidential clients without PKCE.", "default": true } } }, "DeleteAccount": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "description": "The username, typed again." } }, "additionalProperties": false }, "DeliveryStatus": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "dead" ] }, "DiscoverBody": { "type": "object", "required": [ "issuer" ], "properties": { "issuer": { "type": "string" } }, "additionalProperties": false }, "Discovery": { "type": "object", "description": "The parts of an OpenID discovery document rIDM uses.", "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri" ], "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "jwks_uri": { "type": "string" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint": { "type": "string" }, "userinfo_endpoint": { "type": [ "string", "null" ] } } }, "DiscoverySettings": { "type": "object", "description": "WebFinger issuer discovery (OIDC Discovery §2).", "properties": { "email_domains": { "type": "array", "items": { "type": "string" }, "description": "`acct:user@` resources with one of these domains resolve to\nthis tenant's issuer.", "default": [] } } }, "DownloadTicket": { "type": "object", "required": [ "url", "expires_in" ], "properties": { "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "url": { "type": "string", "description": "The export's URL with the ticket: one `GET` of it, without an\n`Authorization` header, within `expires_in` seconds." } } }, "EditableBy": { "type": "string", "description": "Who may set the attribute.", "enum": [ "user", "admin", "none" ] }, "EmailProviderConfig": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SmtpConfig" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "smtp" ] } } } ] }, { "type": "object", "required": [ "url", "from", "type" ], "properties": { "auth_header": { "type": [ "string", "null" ] }, "from": { "type": "string" }, "type": { "type": "string", "enum": [ "http" ] }, "url": { "type": "string" } } } ], "description": "Per-tenant email delivery: SMTP, or an HTTP webhook receiving JSON." }, "EmailSettings": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/EmailSettingsView" }, { "type": "null" } ] }, { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/EmailSource" } } } ] }, "EmailSettingsView": { "oneOf": [ { "type": "object", "required": [ "host", "port", "password_set", "from", "security", "type" ], "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "password_set": { "type": "boolean" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "security": { "type": "string" }, "type": { "type": "string", "enum": [ "smtp" ] }, "username": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "url", "auth_header_set", "from", "type" ], "properties": { "auth_header_set": { "type": "boolean" }, "from": { "type": "string" }, "type": { "type": "string", "enum": [ "http" ] }, "url": { "type": "string" } } } ], "description": "Email settings as shown to administrators (no password or auth header)." }, "EmailSource": { "type": "string", "description": "Where email for the tenant goes.", "enum": [ "tenant", "server_default", "none" ] }, "Enrolled": { "type": "object", "description": "Answer of a completed enrolment: recovery codes when a fresh set was\nissued (the first factor, or an authenticator app, which always renews\nthem), shown once.", "properties": { "recovery_codes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "Enrolment": { "type": "object", "description": "What the UI needs to add the account to an authenticator app.", "required": [ "secret", "otpauth_uri", "issuer", "account", "digits", "period" ], "properties": { "account": { "type": "string" }, "digits": { "type": "integer", "format": "int32", "minimum": 0 }, "issuer": { "type": "string" }, "otpauth_uri": { "type": "string" }, "period": { "type": "integer", "format": "int64", "minimum": 0 }, "secret": { "type": "string", "description": "Base32 secret for manual entry." } } }, "ExpiringKey": { "type": "object", "required": [ "kid", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "kid": { "type": "string" } } }, "ExportedTenant": { "type": "object", "required": [ "slug", "display_name" ], "properties": { "display_name": { "type": "string" }, "slug": { "type": "string" } } }, "Exposure": { "type": "string", "enum": [ "id_token", "userinfo", "access_token" ] }, "FeatureFlag": { "type": "object", "description": "One feature flag. Stored documents from before descriptions and\norganizations existed held a bare `true`/`false`, which still loads.", "required": [ "enabled" ], "properties": { "description": { "type": [ "string", "null" ], "description": "What the flag switches, for the people who toggle it." }, "enabled": { "type": "boolean", "description": "The tenant-wide value." }, "organizations": { "type": "object", "description": "Values for particular organizations, by organization slug; they win\nover `enabled` for users signed in to that organization.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } } } }, "FieldChange": { "type": "object", "required": [ "field", "from", "to" ], "properties": { "field": { "type": "string" }, "from": {}, "to": {} } }, "FieldError": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }, "GenerationInfo": { "type": "object", "description": "A generation as the status report shows it.", "required": [ "version", "backend", "loaded" ], "properties": { "backend": { "type": "string", "description": "`env` for `MASTER_KEY` / `MASTER_KEY_PREVIOUS`, else the custody\nbackend that wrapped it." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "key_ref": { "type": [ "string", "null" ], "description": "The backend key that wrapped it; absent for `env`." }, "loaded": { "type": "boolean", "description": "Whether this node holds the data key (it can decrypt rows under it)." }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "GrantableRole": { "allOf": [ { "$ref": "#/components/schemas/Role" }, { "type": "object", "required": [ "grantable" ], "properties": { "grantable": { "type": "boolean" } } } ], "description": "A tenant role, and whether this caller may grant it inside the\norganization. Roles carrying admin permissions the caller does not hold\nthere are listed but not grantable." }, "Group": { "type": "object", "required": [ "id", "tenant_id", "name", "attributes", "created_at", "updated_at" ], "properties": { "attributes": {}, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GroupDetail": { "allOf": [ { "$ref": "#/components/schemas/Group" }, { "type": "object", "required": [ "roles", "member_count" ], "properties": { "member_count": { "type": "integer", "format": "int64" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "Roles assigned to this group itself (ancestors' roles are inherited at runtime)." } } } ] }, "GroupDoc": { "type": "object", "properties": { "attributes": {}, "description": { "type": [ "string", "null" ], "default": null }, "path": { "type": "array", "items": { "type": "string" }, "description": "Names from the root down; the last element is the group's own name.", "default": [] }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Role references (see `RoleDoc::composites`).", "default": [] } }, "additionalProperties": false }, "GroupUpdate": { "type": "object", "properties": { "attributes": {}, "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": [ "string", "null" ], "default": null }, "parent_id": { "type": [ "string", "null" ], "format": "uuid", "default": null } }, "additionalProperties": false }, "IdTokenEncryptionConfig": { "type": "object", "description": "`id_token_encryption` column.", "required": [ "alg", "enc" ], "properties": { "alg": { "type": "string", "description": "`RSA-OAEP-256` or `RSA-OAEP`." }, "enc": { "type": "string", "description": "`A256GCM` or `A128GCM`." } } }, "Identities": { "type": "object", "description": "The user's linked identities and the providers they could still link.", "required": [ "linked", "available" ], "properties": { "available": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIdentityProvider" }, "description": "Enabled providers without a link yet." }, "linked": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedIdentity" } } } }, "IdentityProvider": { "type": "object", "required": [ "id", "tenant_id", "alias", "kind", "display_name", "enabled", "hidden", "client_id", "client_secret_set", "token_endpoint_auth_method", "scopes", "pkce", "link_policy", "trust_email", "mappers", "sort_order", "created_at", "updated_at" ], "properties": { "alias": { "type": "string" }, "authorization_endpoint": { "type": [ "string", "null" ] }, "client_id": { "type": "string" }, "client_secret_set": { "type": "boolean", "description": "A client secret is stored (it is never returned)." }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": "string" }, "enabled": { "type": "boolean" }, "hidden": { "type": "boolean", "description": "Not offered on the login page; reachable through a direct link." }, "id": { "type": "string", "format": "uuid" }, "issuer": { "type": [ "string", "null" ] }, "jwks_uri": { "type": [ "string", "null" ] }, "kerberos": { "oneOf": [ { "$ref": "#/components/schemas/KerberosUpstream", "description": "The Kerberos settings of a `kerberos` provider." }, { "type": "null" } ] }, "kind": { "$ref": "#/components/schemas/IdpKind" }, "ldap": { "oneOf": [ { "$ref": "#/components/schemas/LdapUpstream", "description": "The directory settings of an `ldap` provider." }, { "type": "null" } ] }, "link_policy": { "$ref": "#/components/schemas/LinkPolicy" }, "mappers": { "$ref": "#/components/schemas/IdpMappers" }, "pkce": { "type": "boolean" }, "preset": { "type": [ "string", "null" ], "description": "`google`, `microsoft`, `github`, `apple`, `gitlab` or none." }, "saml": { "oneOf": [ { "$ref": "#/components/schemas/SamlUpstream", "description": "The SAML settings of a `saml` provider." }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "sort_order": { "type": "integer", "format": "int32" }, "tenant_id": { "type": "string", "format": "uuid" }, "token_endpoint": { "type": [ "string", "null" ] }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/IdpAuthMethod" }, "trust_email": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" }, "userinfo_endpoint": { "type": [ "string", "null" ] } } }, "IdentityProviderDoc": { "type": "object", "description": "An upstream identity provider; the client secret is never part of it.", "properties": { "alias": { "type": "string", "default": "" }, "authorization_endpoint": { "type": [ "string", "null" ], "default": null }, "client_id": { "type": "string", "default": "" }, "display_name": { "type": "string", "default": "" }, "enabled": { "type": "boolean", "default": true }, "hidden": { "type": "boolean", "default": false }, "issuer": { "type": [ "string", "null" ], "default": null }, "jwks_uri": { "type": [ "string", "null" ], "default": null }, "kerberos": { "oneOf": [ { "$ref": "#/components/schemas/KerberosDoc", "description": "A `kerberos` provider's settings (the keytab is a secret: never\nexported, kept on import, uploaded afterwards on a new provider)." }, { "type": "null" } ], "default": null }, "kind": { "$ref": "#/components/schemas/IdpKind", "default": "oidc" }, "ldap": { "oneOf": [ { "$ref": "#/components/schemas/LdapSettings", "description": "An `ldap` provider's directory settings (the bind password is a\nsecret: never exported, kept on import, set afterwards on a new\nprovider; the sync status is not configuration)." }, { "type": "null" } ], "default": null }, "link_policy": { "$ref": "#/components/schemas/LinkPolicy", "default": "verified_email" }, "mappers": { "$ref": "#/components/schemas/IdpMappers", "default": { "attributes": {}, "email": null, "email_verified": null, "subject": null, "username": null } }, "pkce": { "type": "boolean", "default": true }, "preset": { "type": [ "string", "null" ], "default": null }, "saml": { "oneOf": [ { "$ref": "#/components/schemas/SamlUpstreamSettings", "description": "A `saml` provider's settings (`metadata_url` included; the refresh\nstatus is not configuration)." }, { "type": "null" } ], "default": null }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [] }, "sort_order": { "type": "integer", "format": "int32", "default": 0 }, "token_endpoint": { "type": [ "string", "null" ], "default": null }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/IdpAuthMethod", "default": "client_secret_basic" }, "trust_email": { "type": "boolean", "default": false }, "userinfo_endpoint": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "IdentityProviderUpdate": { "type": "object", "properties": { "alias": { "type": [ "string", "null" ], "default": null }, "authorization_endpoint": { "type": [ "string", "null" ], "default": null }, "client_id": { "type": [ "string", "null" ], "default": null }, "client_secret": { "type": [ "string", "null" ], "description": "A new secret, or `null` to clear it.", "default": null }, "display_name": { "type": [ "string", "null" ], "default": null }, "enabled": { "type": [ "boolean", "null" ], "default": null }, "hidden": { "type": [ "boolean", "null" ], "default": null }, "issuer": { "type": [ "string", "null" ], "default": null }, "jwks_uri": { "type": [ "string", "null" ], "default": null }, "kerberos": { "oneOf": [ { "$ref": "#/components/schemas/KerberosSettings", "description": "A `kerberos` provider's settings, replaced as a whole (a missing\n`keytab` keeps the stored one)." }, { "type": "null" } ], "default": null }, "kind": { "oneOf": [ { "$ref": "#/components/schemas/IdpKind" }, { "type": "null" } ], "default": null }, "ldap": { "oneOf": [ { "$ref": "#/components/schemas/LdapSettings", "description": "An `ldap` provider's settings, replaced as a whole (a missing\n`bind_password` keeps the stored one)." }, { "type": "null" } ], "default": null }, "link_policy": { "oneOf": [ { "$ref": "#/components/schemas/LinkPolicy" }, { "type": "null" } ], "default": null }, "mappers": { "oneOf": [ { "$ref": "#/components/schemas/IdpMappers" }, { "type": "null" } ], "default": null }, "pkce": { "type": [ "boolean", "null" ], "default": null }, "saml": { "oneOf": [ { "$ref": "#/components/schemas/SamlUpstreamSettings", "description": "A `saml` provider's settings, replaced as a whole." }, { "type": "null" } ], "default": null }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "sort_order": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "token_endpoint": { "type": [ "string", "null" ], "default": null }, "token_endpoint_auth_method": { "oneOf": [ { "$ref": "#/components/schemas/IdpAuthMethod" }, { "type": "null" } ], "default": null }, "trust_email": { "type": [ "boolean", "null" ], "default": null }, "userinfo_endpoint": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "IdentityProviderView": { "allOf": [ { "$ref": "#/components/schemas/IdentityProvider" }, { "type": "object", "required": [ "callback_url" ], "properties": { "callback_url": { "type": "string", "description": "The redirect URI (OIDC, OAuth 2.0) or the assertion consumer\nservice (SAML); empty for a directory (LDAP) or a Kerberos realm,\nwhich have none." }, "saml_sp": { "oneOf": [ { "$ref": "#/components/schemas/SamlSpInfo", "description": "What a SAML IdP is configured with: rIDM's SP entity ID and URLs." }, { "type": "null" } ] } } } ], "description": "A provider with the callback URL the upstream must be told." }, "IdpAuthMethod": { "type": "string", "description": "How the client authenticates at the token endpoint.", "enum": [ "client_secret_basic", "client_secret_post", "none" ] }, "IdpKind": { "type": "string", "description": "The protocol an upstream provider speaks.", "enum": [ "oidc", "oauth2", "saml", "ldap", "kerberos" ] }, "IdpMappers": { "type": "object", "description": "Where the identity's fields come from in the upstream claims (ID token,\nthen userinfo). Values are claim names; a dot descends into an object.", "properties": { "attributes": { "type": "object", "description": "Profile attribute name → claim name, written on every sign-in.", "default": {}, "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "email": { "type": [ "string", "null" ], "description": "`email` when unset.", "default": null }, "email_verified": { "type": [ "string", "null" ], "description": "`email_verified` when unset.", "default": null }, "subject": { "type": [ "string", "null" ], "description": "The stable identifier; `sub` when unset (`id` for GitHub).", "default": null }, "username": { "type": [ "string", "null" ], "description": "`preferred_username` when unset.", "default": null } }, "additionalProperties": false }, "IdpView": { "type": "object", "description": "The IdP side: what to give an SP, and the signing keys.", "required": [ "entity_id", "sso_url", "slo_url", "metadata_url", "init_url", "keys" ], "properties": { "entity_id": { "type": "string" }, "init_url": { "type": "string", "description": "IdP-initiated sign-in: add `?sp=`." }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/SamlKeyView" } }, "metadata_url": { "type": "string" }, "slo_url": { "type": "string" }, "sso_url": { "type": "string" } } }, "ImpersonateBody": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Why: recorded with every audit event of the impersonation (1–500\ncharacters)." } }, "additionalProperties": false }, "ImpersonationPolicy": { "type": "object", "description": "Whether administrators holding `ridm:users:impersonate` may sign in as\nthis tenant's users, and for how long at a time.", "properties": { "enabled": { "type": "boolean", "default": false }, "max_minutes": { "type": "integer", "format": "int32", "description": "The longest an impersonated session lives, in minutes (1–480). It\nnever outlives the tenant's absolute session timeout either.", "default": 60, "minimum": 0 } } }, "ImpersonationTicket": { "type": "object", "required": [ "url", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Open this in a browser to become the user there. It works once, and\nonly until `expires_at`." } } }, "Impersonator": { "type": "object", "description": "The administrator behind an impersonated session.", "required": [ "user_id", "tenant_id", "username" ], "properties": { "tenant_id": { "type": "string", "format": "uuid", "description": "The administrator's own tenant (`master` for a global administrator)." }, "user_id": { "type": "string", "format": "uuid" }, "username": { "type": "string" } } }, "ImportError": { "type": "object", "required": [ "row", "error" ], "properties": { "error": { "type": "string" }, "row": { "type": "integer", "description": "1-based position in the submitted data.", "minimum": 0 }, "username": { "type": [ "string", "null" ] } } }, "ImportReport": { "type": "object", "required": [ "dry_run", "total", "created", "failed", "errors" ], "properties": { "created": { "type": "integer", "minimum": 0 }, "dry_run": { "type": "boolean" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ImportError" } }, "failed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "ImportRow": { "type": "object", "description": "One user to import. `roles` and `groups` are names; `password_hash` is a\nhash produced elsewhere (argon2, bcrypt, pbkdf2, sha, md5 formats) that\nis upgraded transparently at first login; `password` is checked against\nthe tenant policy.", "properties": { "attributes": {}, "email": { "type": [ "string", "null" ], "default": null }, "email_verified": { "type": "boolean", "default": false }, "groups": { "type": "array", "items": { "type": "string" }, "default": [] }, "locale": { "type": [ "string", "null" ], "default": null }, "must_change_password": { "type": "boolean", "default": false }, "password": { "type": [ "string", "null" ], "default": null }, "password_hash": { "type": [ "string", "null" ], "default": null }, "phone": { "type": [ "string", "null" ], "default": null }, "phone_verified": { "type": "boolean", "default": false }, "roles": { "type": "array", "items": { "type": "string" }, "default": [] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "type": "null" } ], "default": null }, "username": { "type": "string", "default": "" } }, "additionalProperties": false }, "InitialAccessToken": { "type": "object", "description": "An initial access token for dynamic client registration (RFC 7591 §1.2):\nwhat `POST /t/{slug}/register` demands under `dcr.mode =\ninitial_access_token`.", "required": [ "id", "tenant_id", "uses", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "description": "Registrations it allows in all; `null` for no limit." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" }, "uses": { "type": "integer", "format": "int32", "description": "Registrations made with it so far." } } }, "Invitation": { "type": "object", "required": [ "id", "tenant_id", "email", "roles", "groups", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": [ "string", "null" ], "format": "uuid" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "roles": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "tenant_id": { "type": "string", "format": "uuid" } } }, "IpRule": { "type": "object", "description": "An allow or deny rule for a CIDR, for the whole tenant or one client.\nEnforcement is Phase 9.2; this is the configuration.", "required": [ "id", "tenant_id", "action", "cidr", "created_at", "updated_at" ], "properties": { "action": { "$ref": "#/components/schemas/IpRuleAction" }, "cidr": { "type": "string", "description": "Normalized network (`203.0.113.0/24`, `2001:db8::/32`)." }, "client_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IpRuleAction": { "type": "string", "enum": [ "allow", "deny" ] }, "IpRuleDoc": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/IpRuleAction", "default": "deny" }, "cidr": { "type": "string", "default": "" }, "client": { "type": [ "string", "null" ], "default": null }, "description": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "IpRuleUpdate": { "type": "object", "properties": { "action": { "oneOf": [ { "$ref": "#/components/schemas/IpRuleAction" }, { "type": "null" } ], "default": null }, "cidr": { "type": [ "string", "null" ], "default": null }, "description": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "KerberosDoc": { "type": "object", "description": "A Kerberos provider's settings in a tenant document: the directory it\nuses is named by alias, so the document means the same in any tenant.", "properties": { "create_users": { "type": "boolean", "default": false }, "ldap_attribute": { "type": [ "string", "null" ], "default": null }, "ldap_provider": { "type": [ "string", "null" ], "description": "The alias of the LDAP provider that owns the users.", "default": null }, "match_username": { "type": "boolean", "default": true }, "max_skew_seconds": { "type": "integer", "format": "int32", "default": 300 }, "name_form": { "$ref": "#/components/schemas/KerberosNameForm", "default": "local_part" }, "realms": { "type": "array", "items": { "type": "string" }, "default": [] }, "service_principal": { "type": "string", "default": "" }, "trusted_networks": { "type": "array", "items": { "type": "string" }, "default": [] } }, "additionalProperties": false }, "KerberosNameForm": { "type": "string", "description": "How a client principal names a user.", "enum": [ "local_part", "principal" ] }, "KerberosSettings": { "type": "object", "description": "What an administrator sets for a Kerberos provider.", "properties": { "create_users": { "type": "boolean", "description": "Without a directory: create an account (named by the name) for a\nprincipal no account matches.", "default": false }, "keytab": { "type": [ "string", "null" ], "description": "The service's keytab file, base64. Write-only: never returned; left\nout on an update it is kept, an empty string clears it.", "default": null, "writeOnly": true }, "ldap_attribute": { "type": [ "string", "null" ], "description": "The directory attribute holding the name (`sAMAccountName` or\n`userPrincipalName` on Active Directory, `uid` or `krbPrincipalName`\nelsewhere, by the name form, when unset).", "default": null }, "ldap_idp_id": { "type": [ "string", "null" ], "format": "uuid", "description": "An LDAP identity provider that owns these users: the name is looked\nup in the directory and the user imported or refreshed through it.", "default": null }, "match_username": { "type": "boolean", "description": "Without a directory: sign in the local account whose username is the\nname.", "default": true }, "max_skew_seconds": { "type": "integer", "format": "int32", "description": "Allowed clock difference with clients, 30–900 seconds.", "default": 300 }, "name_form": { "$ref": "#/components/schemas/KerberosNameForm", "default": "local_part" }, "realms": { "type": "array", "items": { "type": "string" }, "description": "The client realms whose users may sign in; the service's realm when\nempty.", "default": [] }, "service_principal": { "type": [ "string", "null" ], "description": "The service tickets are issued for, `HTTP/@`, where\n`` is the name browsers use for rIDM. Taken from the keytab\nwhen it holds one service only.", "default": null }, "trusted_networks": { "type": "array", "items": { "type": "string" }, "description": "The networks (CIDRs) from which the login page tries Kerberos on its\nown; elsewhere users click the provider's button.", "default": [] } }, "additionalProperties": false }, "KerberosUpstream": { "type": "object", "description": "The Kerberos side of a `kerberos` identity provider.", "required": [ "service_principal", "realms", "keytab_entries", "keytab_set", "supported", "name_form", "match_username", "create_users", "trusted_networks", "max_skew_seconds" ], "properties": { "create_users": { "type": "boolean" }, "keytab_entries": { "type": "array", "items": { "$ref": "#/components/schemas/KeytabEntryInfo" }, "description": "What the stored keytab holds (never a key)." }, "keytab_set": { "type": "boolean", "description": "A keytab is stored (it is never returned)." }, "ldap_attribute": { "type": [ "string", "null" ] }, "ldap_idp_id": { "type": [ "string", "null" ], "format": "uuid" }, "match_username": { "type": "boolean" }, "max_skew_seconds": { "type": "integer", "format": "int32" }, "name_form": { "$ref": "#/components/schemas/KerberosNameForm" }, "realms": { "type": "array", "items": { "type": "string" } }, "service_principal": { "type": "string" }, "supported": { "type": "boolean", "description": "This build of rIDM can accept tickets (the `kerberos` feature)." }, "trusted_networks": { "type": "array", "items": { "type": "string" } } } }, "KeyPolicy": { "type": "object", "description": "Signing key lifecycle policy.", "properties": { "default_alg": { "$ref": "#/components/schemas/SigningAlg", "description": "Algorithm for new keys created by rotation / on demand.", "default": "RS256" }, "retire_overlap_hours": { "type": "integer", "format": "int32", "description": "How long a retired key stays published for verification.", "default": 24, "minimum": 0 }, "rotation_interval_days": { "type": "integer", "format": "int32", "description": "Rotate the active key after this many days (0 = never automatically).", "default": 90, "minimum": 0 }, "rsa_bits": { "$ref": "#/components/schemas/RsaBits", "default": "B2048" } } }, "KeyStatus": { "type": "string", "description": "Lifecycle: pending (published, not yet signing) → active (signing) →\nretiring (published for verification only) → revoked (unpublished).", "enum": [ "pending", "active", "retiring", "revoked" ] }, "KeyTransport": { "type": "string", "description": "How the content key travels.", "enum": [ "rsa-oaep-mgf1p", "rsa-oaep-sha256" ] }, "KeytabBody": { "type": "object", "required": [ "keytab" ], "properties": { "keytab": { "type": "string", "description": "A keytab file, base64." } }, "additionalProperties": false }, "KeytabEntryInfo": { "type": "object", "description": "What a keytab entry says, without its key: what the admin API shows.", "required": [ "principal", "kvno", "etype", "etype_name", "supported" ], "properties": { "etype": { "type": "integer", "format": "int32" }, "etype_name": { "type": "string", "description": "e.g. `aes256-cts-hmac-sha1-96`." }, "kvno": { "type": "integer", "format": "int32", "minimum": 0 }, "principal": { "type": "string" }, "supported": { "type": "boolean", "description": "rIDM can use this key (AES)." } } }, "KeytabReport": { "type": "object", "description": "What a keytab holds, for the administrator to check before creating a\nKerberos provider with it.", "required": [ "entries", "service_principals", "supported" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/KeytabEntryInfo" } }, "service_principals": { "type": "array", "items": { "type": "string" }, "description": "The services it has an AES key for (a provider needs one of them)." }, "supported": { "type": "boolean", "description": "This build of rIDM can accept tickets (the `kerberos` feature)." } } }, "LdapEditMode": { "type": "string", "description": "Whether rIDM writes back to the directory.", "enum": [ "read_only", "writable" ] }, "LdapMembership": { "type": "string", "description": "What a group's member attribute holds.", "enum": [ "dn", "username" ] }, "LdapScope": { "type": "string", "enum": [ "subtree", "one" ] }, "LdapSettings": { "type": "object", "description": "What an administrator sets for a directory. Attributes and filters left\nout take the vendor's defaults.", "properties": { "bind_dn": { "type": [ "string", "null" ], "description": "The service account that searches (and, when writable, writes);\nnone searches anonymously.", "default": null }, "bind_password": { "type": [ "string", "null" ], "description": "The service account's password. Write-only: never returned; left\nout on an update it is kept, an empty string clears it.", "default": null, "writeOnly": true }, "ca_certificate": { "type": [ "string", "null" ], "description": "PEM certificate(s) the directory's certificate must chain to (an\ninternal CA); none trusts the platform's roots.", "default": null }, "edit_mode": { "$ref": "#/components/schemas/LdapEditMode", "default": "read_only" }, "full_sync_interval_hours": { "type": "integer", "format": "int32", "description": "A full sync, which also disables the users who left the directory\n(or were disabled in it), every this many hours (1–720).", "default": 24 }, "group_member_attribute": { "type": [ "string", "null" ], "description": "The attribute listing a group's members (`member`, `memberUid`).", "default": null }, "group_membership": { "$ref": "#/components/schemas/LdapMembership", "default": "dn" }, "group_name_attribute": { "type": [ "string", "null" ], "description": "The attribute a synced group's name comes from (`cn`).", "default": null }, "group_object_filter": { "type": [ "string", "null" ], "default": null }, "group_parent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The rIDM group synced groups are created under; none makes them\ntop-level.", "default": null }, "groups_dn": { "type": [ "string", "null" ], "description": "Where groups are searched; none turns group sync off.", "default": null }, "login_attributes": { "type": "array", "items": { "type": "string" }, "description": "The attributes a sign-in identifier is matched against; the username\nattribute and `mail` when empty.", "default": [] }, "search_scope": { "$ref": "#/components/schemas/LdapScope", "default": "subtree" }, "starttls": { "type": "boolean", "description": "Upgrade an `ldap://` connection with StartTLS.", "default": false }, "sync_interval_minutes": { "type": "integer", "format": "int32", "description": "Incremental sync every this many minutes (5–10080); 0 turns the\nperiodic sync off (users are still imported and refreshed when they\nsign in).", "default": 60 }, "timeout_secs": { "type": "integer", "format": "int32", "description": "Seconds a connection or an operation may take (1–60).", "default": 10 }, "url": { "type": "string", "description": "`ldaps://host[:port]`, or `ldap://host[:port]` with `starttls`.\nPlain `ldap://` is accepted for loopback hosts only.", "default": "" }, "user_object_filter": { "type": [ "string", "null" ], "description": "Which entries are users, e.g. `(objectClass=inetOrgPerson)`.", "default": null }, "username_attribute": { "type": [ "string", "null" ], "description": "The attribute a new account's username comes from (`uid`,\n`sAMAccountName`).", "default": null }, "users_dn": { "type": "string", "description": "Where users are searched.", "default": "" }, "uuid_attribute": { "type": [ "string", "null" ], "description": "The attribute that never changes for an entry (`entryUUID`,\n`objectGUID`): what the linked identity is keyed by.", "default": null }, "vendor": { "$ref": "#/components/schemas/LdapVendor", "default": "other" } }, "additionalProperties": false }, "LdapSyncBody": { "type": "object", "properties": { "full": { "type": "boolean", "description": "A full pass (which also disables the users who left the directory)\nrather than the incremental one that is due.", "default": false } }, "additionalProperties": false }, "LdapSyncStats": { "type": "object", "description": "What one sync pass did.", "properties": { "created": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "disabled": { "type": "integer", "format": "int64", "description": "Disabled because the entry left the directory or was disabled there.", "default": 0, "minimum": 0 }, "enabled": { "type": "integer", "format": "int64", "description": "Enabled again because the entry came back.", "default": 0, "minimum": 0 }, "full": { "type": "boolean", "description": "A full pass (it may disable users); otherwise incremental.", "default": false }, "groups_created": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "groups_deleted": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "groups_updated": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "memberships_added": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "memberships_removed": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "read": { "type": "integer", "format": "int64", "description": "Directory user entries read.", "default": 0, "minimum": 0 }, "skipped": { "type": "integer", "format": "int64", "description": "Entries that could not be imported (no usable uuid or username, or\nthe link policy refused them); the log says why.", "default": 0, "minimum": 0 }, "updated": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 } } }, "LdapUpstream": { "type": "object", "description": "The directory side of an `ldap` identity provider.", "required": [ "url", "starttls", "vendor", "bind_password_set", "users_dn", "user_object_filter", "search_scope", "username_attribute", "login_attributes", "uuid_attribute", "edit_mode", "sync_interval_minutes", "full_sync_interval_hours", "group_object_filter", "group_name_attribute", "group_member_attribute", "group_membership", "timeout_secs" ], "properties": { "bind_dn": { "type": [ "string", "null" ] }, "bind_password_set": { "type": "boolean", "description": "A bind password is stored (it is never returned)." }, "ca_certificate": { "type": [ "string", "null" ] }, "edit_mode": { "$ref": "#/components/schemas/LdapEditMode" }, "full_sync_interval_hours": { "type": "integer", "format": "int32" }, "group_member_attribute": { "type": "string" }, "group_membership": { "$ref": "#/components/schemas/LdapMembership" }, "group_name_attribute": { "type": "string" }, "group_object_filter": { "type": "string" }, "group_parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "groups_dn": { "type": [ "string", "null" ] }, "last_full_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_sync_error": { "type": [ "string", "null" ], "description": "Why the last sync failed, until one succeeds." }, "last_sync_stats": { "oneOf": [ { "$ref": "#/components/schemas/LdapSyncStats" }, { "type": "null" } ] }, "login_attributes": { "type": "array", "items": { "type": "string" } }, "search_scope": { "$ref": "#/components/schemas/LdapScope" }, "starttls": { "type": "boolean" }, "sync_interval_minutes": { "type": "integer", "format": "int32" }, "timeout_secs": { "type": "integer", "format": "int32" }, "url": { "type": "string" }, "user_object_filter": { "type": "string" }, "username_attribute": { "type": "string" }, "users_dn": { "type": "string" }, "uuid_attribute": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/LdapVendor" } } }, "LdapVendor": { "type": "string", "description": "Which directory server it is: it picks the defaults (attributes,\nfilters) and how a password is written.", "enum": [ "active_directory", "openldap", "other" ] }, "LinkPolicy": { "type": "string", "description": "What happens when an upstream identity signs in for the first time and\na local account with the same email address exists.", "enum": [ "verified_email", "explicit", "always_new" ] }, "LinkRequest": { "type": "object", "required": [ "alias" ], "properties": { "alias": { "type": "string" }, "return_to": { "type": [ "string", "null" ], "description": "The console page to return to (a path on the UI), default the security page." } }, "additionalProperties": false }, "LinkStart": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Send the browser here; the provider brings it back to `return_to`\nwith `?linked=1` or `?link_error=`." } } }, "LinkedIdentity": { "type": "object", "description": "A linked identity with its provider, for listings.", "required": [ "idp_id", "alias", "display_name", "external_subject", "linked_at" ], "properties": { "alias": { "type": "string" }, "display_name": { "type": "string" }, "external_email": { "type": [ "string", "null" ] }, "external_subject": { "type": "string" }, "external_username": { "type": [ "string", "null" ] }, "idp_id": { "type": "string", "format": "uuid" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "linked_at": { "type": "string", "format": "date-time" }, "preset": { "type": [ "string", "null" ] } } }, "LocaleSettings": { "type": "object", "properties": { "default": { "type": "string", "default": "en" }, "supported": { "type": "array", "items": { "type": "string" }, "default": [ "en" ] } } }, "LockoutPolicy": { "type": "object", "description": "Brute-force protection.", "properties": { "ip_max_failures": { "type": "integer", "format": "int32", "description": "Failures from one IP within the window before it is throttled (0 = off).", "default": 100, "minimum": 0 }, "ip_window_minutes": { "type": "integer", "format": "int32", "default": 15, "minimum": 0 }, "lock_minutes": { "type": "integer", "format": "int32", "default": 15, "minimum": 0 }, "max_failures": { "type": "integer", "format": "int32", "description": "Consecutive failures before a user is temporarily locked (0 = off).", "default": 10, "minimum": 0 } } }, "LogEntry": { "type": "object", "description": "A delivery log entry without the message body (bodies carry links and\ncodes that must not be readable after the fact).", "required": [ "id", "channel", "event", "recipient", "status", "attempts", "max_attempts", "next_attempt_at", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "channel": { "$ref": "#/components/schemas/MessageChannel" }, "created_at": { "type": "string", "format": "date-time" }, "event": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "max_attempts": { "type": "integer", "format": "int32" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "recipient": { "type": "string" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "subject": { "type": [ "string", "null" ] } } }, "MapperDoc": { "type": "object", "properties": { "client": { "type": [ "string", "null" ], "default": null }, "config": {}, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "MasterStatus": { "allOf": [ { "$ref": "#/components/schemas/StatusReport" }, { "type": "object", "required": [ "pending_rows" ], "properties": { "pending_rows": { "type": "integer", "format": "int64", "description": "Encrypted rows the next rotation rewrites: under an older generation,\nor still XChaCha20-Poly1305." } } } ] }, "Me": { "type": "object", "required": [ "user_id", "username", "tenant_id", "tenant_slug", "scope", "roles", "permissions", "organization_permissions" ], "properties": { "organization": { "oneOf": [ { "$ref": "#/components/schemas/MeOrganization" }, { "type": "null" } ] }, "organization_permissions": { "type": "array", "items": { "type": "string" }, "description": "What the caller may do inside `organization`: the tenant-wide\npermissions plus anything granted within it. Empty without one." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Tenant-wide permissions: what every route outside an organization\nchecks." }, "roles": { "type": "array", "items": { "type": "string" } }, "scope": { "$ref": "#/components/schemas/AdminScope" }, "tenant_id": { "type": "string", "format": "uuid" }, "tenant_slug": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "username": { "type": "string" } } }, "MeOrganization": { "type": "object", "description": "The organization the caller's sign-in acts in.", "required": [ "id", "slug", "display_name" ], "properties": { "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" } } }, "Member": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "required": [ "joined_at" ], "properties": { "joined_at": { "type": "string", "format": "date-time" } } } ], "description": "A direct member of a group or organization: the user, and when they\njoined (the order member lists are paged in)." }, "MessageChannel": { "type": "string", "enum": [ "email", "sms" ] }, "MessageStatus": { "type": "string", "enum": [ "queued", "sending", "sent", "dead" ] }, "MessageTemplate": { "type": "object", "required": [ "id", "tenant_id", "channel", "event", "locale", "body_text", "created_at", "updated_at" ], "properties": { "body_html": { "type": [ "string", "null" ] }, "body_text": { "type": "string" }, "channel": { "$ref": "#/components/schemas/MessageChannel" }, "created_at": { "type": "string", "format": "date-time" }, "event": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "locale": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MetadataBody": { "type": "object", "required": [ "metadata" ], "properties": { "metadata": { "type": "string", "description": "The SP's metadata document (XML)." } }, "additionalProperties": false }, "MfaMethods": { "type": "object", "description": "Which second-step methods users may enrol. Passkeys are offered as a\nsecond step whenever `AuthMethods::passkey` is on.", "properties": { "email_otp": { "type": "boolean", "description": "One-time code to the account's email address.", "default": false }, "sms_otp": { "type": "boolean", "description": "One-time code to a verified phone number.", "default": false }, "totp": { "type": "boolean", "description": "Authenticator app (TOTP).", "default": true } } }, "MfaPolicy": { "oneOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "off" ] } } }, { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "optional" ] } } }, { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "required" ] } } }, { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "required_for_admins" ] } } }, { "type": "object", "required": [ "roles", "mode" ], "properties": { "mode": { "type": "string", "enum": [ "required_for_roles" ] }, "roles": { "type": "array", "items": { "type": "string" } } } } ] }, "MfaStatus": { "type": "object", "description": "The user's second-factor state.", "required": [ "factors", "recovery_codes", "methods", "policy" ], "properties": { "factors": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" }, "description": "Enrolled factors (`totp`, `webauthn`, `email_otp`, `sms_otp` rows)." }, "methods": { "type": "array", "items": { "type": "string" }, "description": "Factor kinds the tenant offers for enrolment." }, "phone": { "type": [ "string", "null" ], "description": "The phone an SMS enrolment would use, masked." }, "policy": { "type": "string", "description": "The tenant's policy mode (`off`, `optional`, `required`, ...)." }, "recovery_codes": { "type": "integer", "description": "Unused recovery codes.", "minimum": 0 } } }, "MtlsTrustAnchor": { "type": "object", "description": "A certificate authority whose certificates the tenant's `tls_client_auth`\nclients may authenticate with (RFC 8705 §2.1). It may be a root or an\nintermediate: a client's chain only has to reach it.", "required": [ "id", "tenant_id", "name", "certificate_pem", "subject", "fingerprint", "not_before", "not_after", "created_at" ], "properties": { "certificate_pem": { "type": "string", "description": "The CA certificate, PEM." }, "created_at": { "type": "string", "format": "date-time" }, "fingerprint": { "type": "string", "description": "base64url(SHA-256(DER))." }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "not_after": { "type": "string", "format": "date-time" }, "not_before": { "type": "string", "format": "date-time" }, "subject": { "type": "string", "description": "RFC 4514 subject of the CA certificate." }, "tenant_id": { "type": "string", "format": "uuid" } } }, "MtlsTrustAnchorDoc": { "type": "object", "description": "A trusted client-certificate authority, keyed by its certificate.", "properties": { "certificate_pem": { "type": "string", "default": "" }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NameIdFormat": { "type": "string", "description": "The subject identifier an SP receives.", "enum": [ "persistent", "transient", "email", "unspecified" ] }, "NewClaimMapper": { "type": "object", "description": "Input for creating a claim mapper: `config` is the mapper document\n(`type`, its fields and `include_in`) without the name.", "properties": { "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Restrict to one client; absent applies to every client of the tenant.", "default": null }, "config": {}, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewClient": { "type": "object", "description": "Input for creating a client. Missing fields take type-driven defaults.", "properties": { "access_token_format": { "oneOf": [ { "$ref": "#/components/schemas/AccessTokenFormat" }, { "type": "null" } ], "default": null }, "access_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "allowed_audiences": { "type": "array", "items": { "type": "string" }, "default": [] }, "allowed_grants": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "allowed_scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "backchannel_client_notification_endpoint": { "type": [ "string", "null" ], "default": null }, "backchannel_logout_uri": { "type": [ "string", "null" ], "default": null }, "backchannel_token_delivery_mode": { "oneOf": [ { "$ref": "#/components/schemas/BackchannelDeliveryMode" }, { "type": "null" } ], "default": null }, "client_id": { "type": [ "string", "null" ], "description": "Generated when absent.", "default": null }, "client_type": { "oneOf": [ { "$ref": "#/components/schemas/ClientType" }, { "type": "null" } ], "default": null }, "client_uri": { "type": [ "string", "null" ], "default": null }, "cors_origins": { "type": "array", "items": { "type": "string" }, "default": [] }, "description": { "type": [ "string", "null" ], "default": null }, "dpop_bound_access_tokens": { "type": [ "boolean", "null" ], "default": null }, "frontchannel_logout_uri": { "type": [ "string", "null" ], "default": null }, "id_token_encryption": { "oneOf": [ { "$ref": "#/components/schemas/IdTokenEncryptionConfig" }, { "type": "null" } ], "default": null }, "id_token_scope_claims": { "type": [ "boolean", "null" ], "default": null }, "id_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "initiate_login_uri": { "type": [ "string", "null" ], "default": null }, "jwks": {}, "jwks_uri": { "type": [ "string", "null" ], "default": null }, "logo_uri": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" }, "policy_uri": { "type": [ "string", "null" ], "default": null }, "post_logout_redirect_uris": { "type": "array", "items": { "type": "string" }, "default": [] }, "redirect_uris": { "type": "array", "items": { "type": "string" }, "default": [] }, "refresh_token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "require_consent": { "type": [ "boolean", "null" ], "default": null }, "require_pkce": { "type": [ "boolean", "null" ], "default": null }, "require_pushed_authorization_requests": { "type": [ "boolean", "null" ], "default": null }, "sector_identifier_uri": { "type": [ "string", "null" ], "default": null }, "security_profile": { "oneOf": [ { "$ref": "#/components/schemas/SecurityProfile" }, { "type": "null" } ], "default": null }, "subject_type": { "oneOf": [ { "$ref": "#/components/schemas/ClientSubjectType" }, { "type": "null" } ], "default": null }, "tls_client_auth_san_dns": { "type": [ "string", "null" ], "default": null }, "tls_client_auth_san_email": { "type": [ "string", "null" ], "default": null }, "tls_client_auth_san_ip": { "type": [ "string", "null" ], "default": null }, "tls_client_auth_san_uri": { "type": [ "string", "null" ], "default": null }, "tls_client_auth_subject_dn": { "type": [ "string", "null" ], "default": null }, "tls_client_certificate_bound_access_tokens": { "type": [ "boolean", "null" ], "default": null }, "token_endpoint_auth_method": { "oneOf": [ { "$ref": "#/components/schemas/TokenEndpointAuthMethod" }, { "type": "null" } ], "default": null }, "tos_uri": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "NewDownloadTicket": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "The export to download, as its path and query, e.g.\n`/admin/tenants/acme/users/export?format=csv`." } }, "additionalProperties": false }, "NewEmail": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } }, "additionalProperties": false }, "NewGeneration": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "format": "int32", "description": "The generation now current on this node; the others adopt it within a\nminute. Re-encrypt with `POST /admin/master-key/rotate`.", "minimum": 0 } } }, "NewGroup": { "type": "object", "properties": { "attributes": {}, "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid", "default": null } }, "additionalProperties": false }, "NewIdentityProvider": { "type": "object", "description": "Fields of a new provider. A `preset` fills in everything the preset\nknows (kind, endpoints, scopes, mappers); explicit values win.", "properties": { "alias": { "type": "string", "default": "" }, "authorization_endpoint": { "type": [ "string", "null" ], "default": null }, "client_id": { "type": "string", "default": "" }, "client_secret": { "type": [ "string", "null" ], "default": null }, "display_name": { "type": [ "string", "null" ], "default": null }, "enabled": { "type": [ "boolean", "null" ], "default": null }, "hidden": { "type": [ "boolean", "null" ], "default": null }, "issuer": { "type": [ "string", "null" ], "description": "OIDC: the endpoints are discovered from it when left out.", "default": null }, "jwks_uri": { "type": [ "string", "null" ], "default": null }, "kerberos": { "oneOf": [ { "$ref": "#/components/schemas/KerberosSettings", "description": "Required for a `kerberos` provider, refused for any other." }, { "type": "null" } ], "default": null }, "kind": { "oneOf": [ { "$ref": "#/components/schemas/IdpKind" }, { "type": "null" } ], "default": null }, "ldap": { "oneOf": [ { "$ref": "#/components/schemas/LdapSettings", "description": "Required for an `ldap` provider, refused for any other." }, { "type": "null" } ], "default": null }, "link_policy": { "oneOf": [ { "$ref": "#/components/schemas/LinkPolicy" }, { "type": "null" } ], "default": null }, "mappers": { "oneOf": [ { "$ref": "#/components/schemas/IdpMappers" }, { "type": "null" } ], "default": null }, "pkce": { "type": [ "boolean", "null" ], "default": null }, "preset": { "type": [ "string", "null" ], "default": null }, "saml": { "oneOf": [ { "$ref": "#/components/schemas/SamlUpstreamSettings", "description": "Required for a `saml` provider, refused for any other." }, { "type": "null" } ], "default": null }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "sort_order": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "token_endpoint": { "type": [ "string", "null" ], "default": null }, "token_endpoint_auth_method": { "oneOf": [ { "$ref": "#/components/schemas/IdpAuthMethod" }, { "type": "null" } ], "default": null }, "trust_email": { "type": [ "boolean", "null" ], "default": null }, "userinfo_endpoint": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "NewInitialAccessToken": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "description": "What the token is for (at most 200 characters).", "default": null }, "expires_in_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Seconds until the token expires; absent for a token without expiry.", "default": null, "minimum": 0 }, "max_uses": { "type": [ "integer", "null" ], "format": "int32", "description": "Registrations it allows; absent for no limit.", "default": null, "minimum": 0 } }, "additionalProperties": false }, "NewInvitation": { "type": "object", "properties": { "email": { "type": "string", "default": "" }, "expires_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Days until expiry (default 7).", "default": null, "minimum": 0 }, "groups": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "org_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "roles": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] } }, "additionalProperties": false }, "NewIpRule": { "type": "object", "properties": { "action": { "oneOf": [ { "$ref": "#/components/schemas/IpRuleAction" }, { "type": "null" } ], "default": null }, "cidr": { "type": "string", "description": "A network in CIDR notation, or a single address.", "default": "" }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "description": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "NewMtlsTrustAnchor": { "type": "object", "properties": { "certificate_pem": { "type": "string", "description": "One CA certificate, PEM.", "default": "" }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewOrganization": { "type": "object", "properties": { "attributes": {}, "description": { "type": [ "string", "null" ], "default": null }, "display_name": { "type": "string", "default": "" }, "slug": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewOrganizationDomain": { "type": "object", "properties": { "auto_join": { "type": "boolean", "description": "Auto-join takes effect once the domain is verified.", "default": false }, "domain": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewPermission": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewPersonalAccessToken": { "type": "object", "properties": { "expires_in_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Days until it expires; none means the tenant's maximum (or never\nwhen the tenant sets no maximum).", "default": null, "minimum": 0 }, "name": { "type": "string", "default": "" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "`account` for the self-service API, and admin permission names.", "default": [] } }, "additionalProperties": false }, "NewPhone": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "E.164." } }, "additionalProperties": false }, "NewResourceServer": { "type": "object", "properties": { "allow_offline_access": { "type": [ "boolean", "null" ], "default": null }, "identifier": { "type": "string", "description": "Audience value (`aud`) tokens for this API carry; 1-512 characters.", "default": "" }, "name": { "type": "string", "default": "" }, "signing_alg": { "type": [ "string", "null" ], "default": null }, "token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null } }, "additionalProperties": false }, "NewRole": { "type": "object", "properties": { "client_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewScimToken": { "type": "object", "properties": { "expires_in_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Days until the token expires; absent for a token without expiry.", "default": null, "minimum": 0 }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "NewScope": { "type": "object", "properties": { "claims": { "type": "array", "items": { "type": "string" }, "default": [] }, "description": { "type": [ "string", "null" ], "default": null }, "is_default": { "type": "boolean", "default": false }, "name": { "type": "string", "default": "" }, "resource_server_id": { "type": [ "string", "null" ], "format": "uuid", "default": null } }, "additionalProperties": false }, "NewTenant": { "type": "object", "required": [ "slug", "display_name" ], "properties": { "data_region": { "type": [ "string", "null" ], "description": "The data region to keep the tenant's data in, one of\n`GET /admin/regions`; absent or `home`: the home database. Fixed at\ncreation; `ridm-api move-tenant` moves a tenant later." }, "display_name": { "type": "string" }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/TenantSettings" }, { "type": "null" } ] }, "slug": { "type": "string" } } }, "NewWebhook": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "default": null }, "events": { "type": "array", "items": { "type": "string" }, "default": [] }, "headers": {}, "max_attempts": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "name": { "type": "string", "default": "" }, "url": { "type": "string", "default": "" } }, "additionalProperties": false }, "NotificationPolicy": { "type": "object", "description": "Which security notices users receive (email, or SMS when they have no email).", "properties": { "email_changed": { "type": "boolean", "default": true }, "mfa_changed": { "type": "boolean", "default": true }, "new_device": { "type": "boolean", "default": true }, "password_changed": { "type": "boolean", "default": true } } }, "Op": { "type": "string", "enum": [ "create", "update", "delete" ] }, "Organization": { "type": "object", "description": "A grouping within one tenant: a customer, business unit or team. Users may\nbelong to several; `users.org_id` names the one they belong to first.", "required": [ "id", "tenant_id", "slug", "display_name", "status", "attributes", "created_at", "updated_at" ], "properties": { "attributes": {}, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationStatus" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrganizationDetail": { "allOf": [ { "$ref": "#/components/schemas/Organization" }, { "type": "object", "required": [ "member_count", "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationDomain" } }, "member_count": { "type": "integer", "format": "int64" } } } ] }, "OrganizationDomain": { "type": "object", "description": "An email domain an organization claims. Users with a verified address at a\nverified `auto_join` domain become members as they sign in.", "required": [ "id", "tenant_id", "org_id", "domain", "verification", "auto_join", "created_at", "updated_at" ], "properties": { "auto_join": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "verification": { "type": "string", "description": "The value to publish as a DNS TXT record to prove control of the domain." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrganizationDomainUpdate": { "type": "object", "properties": { "auto_join": { "type": [ "boolean", "null" ], "default": null } }, "additionalProperties": false }, "OrganizationStatus": { "type": "string", "enum": [ "active", "disabled" ] }, "OrganizationUpdate": { "type": "object", "properties": { "attributes": {}, "description": { "type": [ "string", "null" ], "default": null }, "display_name": { "type": [ "string", "null" ], "default": null }, "slug": { "type": [ "string", "null" ], "default": null }, "status": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationStatus" }, { "type": "null" } ], "default": null } }, "additionalProperties": false }, "Page_AuditEvent": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "One audit row: a domain event as recorded, with its place in the\ntenant's hash chain.", "required": [ "id", "seq", "occurred_at", "recorded_at", "name", "actor_type", "payload", "hash" ], "properties": { "actor_id": { "type": [ "string", "null" ], "format": "uuid" }, "actor_type": { "type": "string", "description": "`user`, `client`, `admin` or `system`." }, "hash": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "impersonator_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The administrator behind the event, when it happened in a session\nthey opened as a user (impersonation)." }, "ip": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Dotted event name (`user.created`)." }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "description": "The event's `kind` document (`type` plus its fields)." }, "prev_hash": { "type": [ "string", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "seq": { "type": "integer", "format": "int64", "description": "Position in the chain (per tenant, or the global chain)." }, "subject_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The main entity the event is about (user, client, role, ...), when it has one." }, "tenant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "`None` for global (cross-tenant) events." }, "user_agent": { "type": [ "string", "null" ] } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_ClientView": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Client" }, { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretView" } } } } ], "description": "Client as returned to administrators: every metadata column, plus the\nsecrets' ids and validity windows (never the secrets or their hashes)." } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_Invitation": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "tenant_id", "email", "roles", "groups", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": [ "string", "null" ], "format": "uuid" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "roles": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "tenant_id": { "type": "string", "format": "uuid" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_Member": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "required": [ "joined_at" ], "properties": { "joined_at": { "type": "string", "format": "date-time" } } } ], "description": "A direct member of a group or organization: the user, and when they\njoined (the order member lists are paged in)." } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_Organization": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "A grouping within one tenant: a customer, business unit or team. Users may\nbelong to several; `users.org_id` names the one they belong to first.", "required": [ "id", "tenant_id", "slug", "display_name", "status", "attributes", "created_at", "updated_at" ], "properties": { "attributes": {}, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrganizationStatus" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_RoleHolder": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/RoleAssignment" }, { "type": "object", "properties": { "username": { "type": [ "string", "null" ] } } } ], "description": "A role assignment as the holder listings show it: with the user's\nusername when the principal is a user." } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_Tenant": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "display_name", "status", "settings", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_region": { "type": [ "string", "null" ], "description": "The data region the tenant's data lives in (one of `DATA_REGIONS`);\n`None`: the home database. Set when the tenant is created, changed\nonly by `ridm-api move-tenant`." }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "relocating": { "type": "boolean", "description": "A move to another region is under way: the tenant is unavailable\nuntil it ends." }, "settings": { "$ref": "#/components/schemas/TenantSettings" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/TenantStatus" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Page_UserListItem": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "second_step": { "type": [ "string", "null" ], "description": "`passkey`, `totp` or `otp` (email or SMS codes); `null` when none is enrolled." } } } ], "description": "A listed user: the record plus the strongest second step enrolled, so a\nlist can show it without a request per row." } }, "next_cursor": { "type": [ "string", "null" ] } } }, "PasskeyFinishBody": { "type": "object", "required": [ "credential" ], "properties": { "credential": { "description": "The browser's `navigator.credentials.create` answer." }, "label": { "type": [ "string", "null" ] } } }, "PasswordBody": { "type": "object", "properties": { "must_change": { "type": "boolean", "description": "Force a change at next login (always true for temporary passwords).", "default": false }, "notify": { "type": "boolean", "description": "Email the user that their password changed.", "default": false }, "password": { "type": [ "string", "null" ], "description": "Absent: generate a temporary password and return it once.", "default": null }, "revoke_sessions": { "type": "boolean", "description": "End the user's sessions so the new password is needed everywhere.", "default": false }, "skip_policy": { "type": "boolean", "description": "Skip the tenant policy and history checks.", "default": false } }, "additionalProperties": false }, "PasswordChanged": { "type": "object", "required": [ "signed_out", "password" ], "properties": { "password": { "$ref": "#/components/schemas/PasswordStatus" }, "signed_out": { "type": "integer", "format": "int64", "description": "Other sessions ended.", "minimum": 0 } } }, "PasswordPolicy": { "type": "object", "properties": { "check_breached": { "type": "boolean", "description": "Reject passwords found in breach corpora (Phase 7.5).", "default": false }, "history": { "type": "integer", "format": "int32", "description": "A new password must differ from the last `history` passwords, counting\nthe current one (0 = off, 1 = only the current password).", "default": 5, "minimum": 0 }, "max_age_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Days until a password expires (None = never).", "default": null, "minimum": 0 }, "max_length": { "type": "integer", "format": "int32", "default": 128, "minimum": 0 }, "min_length": { "type": "integer", "format": "int32", "default": 12, "minimum": 0 }, "require_digit": { "type": "boolean", "default": false }, "require_lowercase": { "type": "boolean", "default": false }, "require_symbol": { "type": "boolean", "default": false }, "require_uppercase": { "type": "boolean", "default": false } } }, "PasswordStatus": { "type": "object", "description": "The state of the user's password and the rules a new one must meet.", "required": [ "enabled", "set", "must_change", "policy" ], "properties": { "changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "enabled": { "type": "boolean", "description": "Passwords are a sign-in method of this tenant." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "must_change": { "type": "boolean" }, "policy": { "$ref": "#/components/schemas/PasswordPolicy" }, "set": { "type": "boolean" } } }, "PasswordSummary": { "type": "object", "required": [ "set", "must_change" ], "properties": { "algorithm": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "must_change": { "type": "boolean" }, "set": { "type": "boolean" } } }, "PendingChanges": { "type": "object", "description": "The changes awaiting their code, masked for display.", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "PendingRequest": { "type": "object", "description": "A request waiting on the user, as their account console shows it.", "required": [ "id", "client_id", "client_name", "scopes", "created_at", "expires_at" ], "properties": { "binding_message": { "type": [ "string", "null" ], "description": "The text the client shows on its own device, to compare." }, "client_id": { "type": "string", "format": "uuid", "description": "The client's row id." }, "client_name": { "type": "string" }, "client_uri": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "logo_uri": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "Permission": { "type": "object", "required": [ "id", "tenant_id", "resource_server_id", "name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resource_server_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" } } }, "PermissionDef": { "type": "object", "required": [ "name", "description" ], "properties": { "description": { "type": "string" }, "name": { "type": "string" } } }, "PermissionDoc": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" } }, "additionalProperties": false }, "PermissionModel": { "type": "object", "required": [ "audience", "permissions", "roles" ], "properties": { "audience": { "type": "string" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDef" } }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRoleDoc" } } } }, "PersonalAccessToken": { "type": "object", "description": "A long-lived bearer token a user minted for scripts and integrations.\nThe token itself is shown once; only its hash is kept.", "required": [ "id", "tenant_id", "user_id", "name", "scopes", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "`account` and/or admin permission names, each held by the user when\nthe token was made; at use they are narrowed to what the user still holds." }, "tenant_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" } } }, "PhoneBody": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ], "description": "E.164 number to prove; the account's own when omitted.", "default": null } } }, "Plan": { "type": "object", "required": [ "prune", "changes", "summary" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "prune": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/Summary" } } }, "Preset": { "type": "object", "description": "A well-known provider: everything but the client credentials.", "required": [ "name", "display_name", "kind", "scopes", "token_endpoint_auth_method", "trust_email", "hint" ], "properties": { "authorization_endpoint": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "hint": { "type": "string", "description": "Notes shown to the administrator setting it up." }, "issuer": { "type": [ "string", "null" ] }, "jwks_uri": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/IdpKind" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "subject_claim": { "type": [ "string", "null" ], "description": "Where the identity's fields come from when the provider is not\nplain OpenID Connect." }, "token_endpoint": { "type": [ "string", "null" ] }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/IdpAuthMethod" }, "trust_email": { "type": "boolean", "description": "The provider vouches for the addresses it returns." }, "userinfo_endpoint": { "type": [ "string", "null" ] }, "username_claim": { "type": [ "string", "null" ] } } }, "Preview": { "type": "object", "required": [ "body_text", "vars" ], "properties": { "body_html": { "type": [ "string", "null" ] }, "body_text": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "vars": { "description": "The variables the preview was rendered with." } } }, "PreviewRequest": { "type": "object", "properties": { "channel": { "oneOf": [ { "$ref": "#/components/schemas/MessageChannel" }, { "type": "null" } ], "default": null }, "draft": { "oneOf": [ { "$ref": "#/components/schemas/TemplateBody", "description": "An unsaved draft to render instead of the stored/built-in template." }, { "type": "null" } ], "default": null }, "event": { "type": "string", "default": "" }, "locale": { "type": [ "string", "null" ], "description": "Locale to resolve when no draft is given (default: tenant default).", "default": null }, "vars": { "description": "Extra variables merged over the sample data." } }, "additionalProperties": false }, "Problem": { "type": "object", "description": "RFC 9457 problem details body.", "required": [ "type", "title", "status" ], "properties": { "detail": { "type": [ "string", "null" ] }, "errors": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/FieldError" } }, "status": { "type": "integer", "format": "int32", "minimum": 0 }, "title": { "type": "string" }, "type": { "type": "string" } } }, "Profile": { "type": "object", "description": "The user's profile with the schema the console renders it by.", "required": [ "username", "email_verified", "phone_verified", "attributes", "schema", "pending", "locales" ], "properties": { "attributes": { "description": "Values of the declared attributes (undeclared ones are internal)." }, "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "locale": { "type": [ "string", "null" ] }, "locales": { "type": "array", "items": { "type": "string" }, "description": "Locales the tenant supports, for the locale picker." }, "pending": { "$ref": "#/components/schemas/PendingChanges", "description": "Email or phone changes awaiting their code, masked." }, "phone": { "type": [ "string", "null" ] }, "phone_verified": { "type": "boolean" }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeDef" }, "description": "The declared attributes in form order; `editable_by` says which\nthe user may change." }, "username": { "type": "string" } } }, "ProfilePatch": { "type": "object", "description": "A merge patch: only the fields present change. `attributes` replaces\nthe user-editable attributes (those left out are cleared; attributes\nthe user may not edit are kept whether sent unchanged or not).", "properties": { "attributes": {}, "locale": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "ProfileSchema": { "type": "object", "properties": { "allow_undeclared": { "type": "boolean", "description": "Accept attributes not declared in the schema (stored verbatim, admin-editable only).", "default": false }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeDef" }, "default": [] } } }, "PublicIdentityProvider": { "type": "object", "description": "A provider as the login page and the account console see it.", "required": [ "alias", "display_name" ], "properties": { "alias": { "type": "string" }, "display_name": { "type": "string" }, "preset": { "type": [ "string", "null" ] } } }, "RateLimitPolicy": { "type": "object", "description": "Request ceilings enforced on this tenant's OAuth and sign-in endpoints\n(counted in fixed windows in Valkey, shared by every node). Each limit is\nrequests per `window_secs`; 0 switches that limit off. The deployment-wide\nper-address ceiling (`RATE_LIMIT_IP_PER_MINUTE`) applies on top.", "properties": { "authorize_per_ip": { "type": "integer", "format": "int32", "description": "`/authorize`, `/par` and dynamic registration per client address.", "default": 300, "minimum": 0 }, "enabled": { "type": "boolean", "default": true }, "flows_per_ip": { "type": "integer", "format": "int32", "description": "The browser flow API (flows, recovery, verification, invitations,\ndevice verification, brokering) per client address.", "default": 600, "minimum": 0 }, "tenant_total": { "type": "integer", "format": "int32", "description": "Every limited endpoint together, across all addresses (0 = off).", "default": 0, "minimum": 0 }, "token_per_client": { "type": "integer", "format": "int32", "description": "The same endpoints per authenticated client (counted before the\nsecret is checked, so guessing a secret is bounded too).", "default": 1200, "minimum": 0 }, "token_per_ip": { "type": "integer", "format": "int32", "description": "`/token`, `/introspect`, `/revoke`, `/userinfo`, `/device_authorization` per client address.", "default": 600, "minimum": 0 }, "window_secs": { "type": "integer", "format": "int32", "description": "Window length in seconds (1..=3600).", "default": 60, "minimum": 0 } } }, "RecentEvent": { "type": "object", "description": "One of the newest audit events, with its actor and subject named.", "required": [ "id", "name", "occurred_at", "actor_type" ], "properties": { "actor": { "type": [ "string", "null" ], "description": "The actor's username, when the actor is a user of this tenant." }, "actor_type": { "type": "string", "description": "`user`, `client`, `admin` or `system`." }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Dotted event name (`user.created`)." }, "occurred_at": { "type": "string", "format": "date-time" }, "subject": { "type": [ "string", "null" ], "description": "The subject's username or client name, when it is one of this tenant's." } } }, "RecoveryCodes": { "type": "object", "required": [ "recovery_codes" ], "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" } } } }, "Region": { "type": "object", "description": "A place a tenant's data can live (data residency, `DATA_REGIONS`).", "required": [ "name", "home", "dedicated_cache", "tenants" ], "properties": { "dedicated_cache": { "type": "boolean", "description": "The region keeps its tenants' sessions and cached rows in a Valkey\nof its own (`REDIS_URL_`) rather than the shared one." }, "home": { "type": "boolean" }, "name": { "type": "string", "description": "What `data_region` names; `home` is the `DATABASE_URL` database." }, "tenants": { "type": "integer", "format": "int64", "description": "Tenants placed in it." } } }, "RegistrationPolicy": { "type": "object", "properties": { "allowed_email_domains": { "type": "array", "items": { "type": "string" }, "description": "Only these email domains may self-register (empty = any). (A CAPTCHA\non registration is `captcha.on_registration`.)", "default": [] }, "enabled": { "type": "boolean", "default": false }, "privacy_url": { "type": [ "string", "null" ], "default": null }, "require_email_verification": { "type": "boolean", "default": true }, "require_terms": { "type": "boolean", "default": false }, "terms_url": { "type": [ "string", "null" ], "default": null } } }, "RegistrationTokenView": { "type": "object", "required": [ "registration_access_token", "registration_client_uri" ], "properties": { "registration_access_token": { "type": "string" }, "registration_client_uri": { "type": "string" } } }, "Requeued": { "type": "object", "description": "How many dead deliveries went back on the queue.", "required": [ "requeued" ], "properties": { "requeued": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ResourceServer": { "type": "object", "required": [ "id", "tenant_id", "identifier", "name", "allow_offline_access", "built_in", "created_at", "updated_at" ], "properties": { "allow_offline_access": { "type": "boolean" }, "built_in": { "type": "boolean", "description": "Seeded by a migration (`urn:ridm:admin`); cannot be changed or deleted." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string" }, "name": { "type": "string" }, "signing_alg": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string", "format": "uuid" }, "token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ResourceServerDetail": { "allOf": [ { "$ref": "#/components/schemas/ResourceServer" }, { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } ] }, "ResourceServerDoc": { "type": "object", "properties": { "allow_offline_access": { "type": "boolean", "default": true }, "identifier": { "type": "string", "default": "" }, "name": { "type": "string", "default": "" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDoc" }, "default": [] }, "signing_alg": { "type": [ "string", "null" ], "default": null }, "token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null } }, "additionalProperties": false }, "ResourceServerUpdate": { "type": "object", "description": "Partial resource server update; the identifier is immutable.", "properties": { "allow_offline_access": { "type": [ "boolean", "null" ], "default": null }, "name": { "type": [ "string", "null" ], "default": null }, "signing_alg": { "type": [ "string", "null" ], "default": null }, "token_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null } }, "additionalProperties": false }, "RevealView": { "allOf": [ { "$ref": "#/components/schemas/ClientView" }, { "type": "object", "properties": { "client_secret": { "type": [ "string", "null" ] } } } ], "description": "A view plus a secret that is shown exactly once." }, "Revoked": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "integer", "format": "int64", "minimum": 0 } } }, "RiskPolicy": { "type": "object", "description": "Risk-based adaptive authentication.\n\nEvery signal a sign-in raises contributes its weight; the sum is measured\nagainst two thresholds, so a tenant decides both how much each signal\ncounts and how much is too much. `step_up_at` demands the second factor\nfor that sign-in even where the MFA policy would not, and `block_at`\nrefuses it outright. A threshold of 0 switches that outcome off, which is\nhow a tenant runs the policy in step-up-only mode.\n\nNothing here has any effect while `enabled` is false, which is the default:\na deployment that upgrades into this release signs its users in exactly as\nbefore until an administrator turns it on.", "properties": { "block_at": { "type": "integer", "format": "int32", "description": "Score at or above which the sign-in is refused (0 = never block).", "default": 100, "minimum": 0 }, "enabled": { "type": "boolean", "default": false }, "impossible_travel_kmh": { "type": "integer", "format": "int32", "description": "Travel faster than this between two sign-ins is impossible. Only\nreachable when the geo source yields coordinates.", "default": 900, "minimum": 0 }, "step_up_at": { "type": "integer", "format": "int32", "description": "Score at or above which the sign-in must pass a second factor\n(0 = never step up).", "default": 50, "minimum": 0 }, "velocity_max_failures": { "type": "integer", "format": "int32", "description": "Failures from the address within the window that raise the signal\n(0 = off).", "default": 10, "minimum": 0 }, "velocity_window_minutes": { "type": "integer", "format": "int32", "description": "Window the velocity signal counts failed sign-ins from one address in.", "default": 15, "minimum": 0 }, "weights": { "$ref": "#/components/schemas/RiskWeights", "default": { "impossible_travel": 60, "new_country": 50, "new_device": 20, "velocity": 40 } } } }, "RiskWeights": { "type": "object", "description": "What each signal contributes to the score. With the defaults, a new\ncountry alone steps up, a new country on a new browser steps up, and\nimpossible travel on a new browser from a new country blocks.", "properties": { "impossible_travel": { "type": "integer", "format": "int32", "description": "The distance from the last known location cannot be covered in the\ntime since it was seen.", "default": 60, "minimum": 0 }, "new_country": { "type": "integer", "format": "int32", "description": "The user has never signed in from this country.", "default": 50, "minimum": 0 }, "new_device": { "type": "integer", "format": "int32", "description": "The browser has no trusted-device cookie and no earlier session.", "default": 20, "minimum": 0 }, "velocity": { "type": "integer", "format": "int32", "description": "The address is behind an unusual number of recent failures.", "default": 40, "minimum": 0 } } }, "Role": { "type": "object", "required": [ "id", "tenant_id", "name", "built_in", "created_at", "updated_at" ], "properties": { "built_in": { "type": "boolean", "description": "Seeded by a migration (the `ridm:*` admin roles); cannot be renamed or deleted." }, "client_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Client-scoped role when set; realm-wide otherwise." }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RoleAssignment": { "type": "object", "required": [ "id", "tenant_id", "role_id", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "group_id": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "role_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "RoleDetail": { "allOf": [ { "$ref": "#/components/schemas/Role" }, { "type": "object", "required": [ "composites", "permissions" ], "properties": { "composites": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } ] }, "RoleDoc": { "type": "object", "properties": { "client": { "type": [ "string", "null" ], "description": "Public `client_id` of the client the role belongs to; absent = realm role.", "default": null }, "composites": { "type": "array", "items": { "type": "string" }, "description": "Role references: `name` for realm roles, `client_id/name` for client roles.", "default": [] }, "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "`resource server identifier#permission name`.", "default": [] } }, "additionalProperties": false }, "RoleHolder": { "allOf": [ { "$ref": "#/components/schemas/RoleAssignment" }, { "type": "object", "properties": { "username": { "type": [ "string", "null" ] } } } ], "description": "A role assignment as the holder listings show it: with the user's\nusername when the principal is a user." }, "RoleUpdate": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "default": null }, "name": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "RotateBody": { "type": "object", "properties": { "grace_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "How long the previous secret keeps working (default 24h, `0` retires\nit at once, at most 30 days).", "default": null } }, "additionalProperties": false }, "RotationReport": { "type": "object", "required": [ "target_version", "rewritten", "failed" ], "properties": { "failed": { "type": "object", "description": "Rows that could not be re-encrypted (unknown generation, corrupt blob).", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 }, "propertyNames": { "type": "string" } }, "rewritten": { "type": "object", "description": "Rows re-encrypted per table.", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 }, "propertyNames": { "type": "string" } }, "target_version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "RsaBits": { "type": "string", "description": "RSA modulus size for new RSA keys.", "enum": [ "B2048", "B3072", "B4096" ] }, "SamlAttribute": { "type": "object", "description": "One released attribute: the value of a claim, under the SP's name.", "required": [ "claim", "name" ], "properties": { "claim": { "type": "string", "description": "A claim the client's scopes, the profile schema or a claim mapper\nproduce (`email`, `name`, `groups`, `roles`, ...)." }, "friendly_name": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "The attribute's `Name`, e.g. `urn:oid:0.9.2342.19200300.100.1.3`." }, "name_format": { "$ref": "#/components/schemas/AttributeNameFormat" } } }, "SamlKeyStatus": { "type": "string", "description": "Lifecycle of a SAML signing key: `pending` (in metadata, not signing)\n→ `active` (signing) → `retiring` (in metadata, not signing) → deleted.", "enum": [ "pending", "active", "retiring" ] }, "SamlKeyView": { "type": "object", "description": "A key as metadata and the console show it.", "required": [ "id", "status", "certificate", "sha256_fingerprint", "not_after", "created_at" ], "properties": { "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "certificate": { "type": "string", "description": "base64 DER." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "not_after": { "type": "string", "format": "date-time" }, "sha256_fingerprint": { "type": "string", "description": "SHA-256 of the certificate, hex with colons, as SP consoles show it." }, "status": { "$ref": "#/components/schemas/SamlKeyStatus" } } }, "SamlMetadataBody": { "type": "object", "properties": { "metadata": { "type": [ "string", "null" ], "description": "The IdP's metadata document (pasted or uploaded)." }, "url": { "type": [ "string", "null" ], "description": "Or where to fetch it; it is kept as the provider's `metadata_url`." } }, "additionalProperties": false }, "SamlServiceProvider": { "type": "object", "description": "The SAML side of a `saml` client.", "required": [ "client_id", "tenant_id", "entity_id", "acs_urls", "slo_binding", "name_id_format", "signing_certificates", "require_signed_requests", "sign_response", "sign_assertion", "encrypt_assertion", "data_encryption", "key_transport", "allow_idp_initiated", "attributes", "assertion_ttl_secs", "created_at", "updated_at" ], "properties": { "acs_urls": { "type": "array", "items": { "type": "string" }, "description": "HTTP-POST assertion consumer services; the position is the index\nand the first is the default." }, "allow_idp_initiated": { "type": "boolean" }, "assertion_ttl_secs": { "type": "integer", "format": "int32" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/SamlAttribute" } }, "client_id": { "type": "string", "format": "uuid", "description": "The client's row id." }, "created_at": { "type": "string", "format": "date-time" }, "data_encryption": { "$ref": "#/components/schemas/DataEncryption" }, "default_relay_state": { "type": [ "string", "null" ] }, "encrypt_assertion": { "type": "boolean" }, "encryption_certificate": { "type": [ "string", "null" ], "description": "base64 DER certificate assertions are encrypted to." }, "entity_id": { "type": "string" }, "key_transport": { "$ref": "#/components/schemas/KeyTransport" }, "name_id_format": { "$ref": "#/components/schemas/NameIdFormat" }, "require_signed_requests": { "type": "boolean" }, "sign_assertion": { "type": "boolean" }, "sign_response": { "type": "boolean" }, "signing_certificates": { "type": "array", "items": { "type": "string" }, "description": "base64 DER certificates the SP signs requests with." }, "slo_binding": { "$ref": "#/components/schemas/SloBinding" }, "slo_url": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SamlSpDoc": { "allOf": [ { "type": "object" }, { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ClientStatus" } } } ], "description": "A SAML service provider: its registration as `POST /saml/service-providers`\ntakes it, keyed by the public client id, plus `status`." }, "SamlSpInfo": { "type": "object", "description": "rIDM as the service provider of one SAML IdP.", "required": [ "entity_id", "metadata_url", "acs_url", "slo_url" ], "properties": { "acs_url": { "type": "string" }, "entity_id": { "type": "string" }, "metadata_url": { "type": "string", "description": "rIDM's SP metadata, to give the IdP (the entity ID is this URL)." }, "slo_url": { "type": "string" } } }, "SamlSpInput": { "type": "object", "description": "A service provider as the admin API reads and writes it: the client's\nown fields and the SAML settings side by side.", "properties": { "acs_urls": { "type": "array", "items": { "type": "string" }, "default": [] }, "allow_idp_initiated": { "type": [ "boolean", "null" ], "default": null }, "allowed_scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Scopes whose claims may be released as attributes.", "default": null }, "assertion_ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "attributes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SamlAttribute" }, "default": null }, "client_id": { "type": [ "string", "null" ], "description": "The public client id; generated when absent.", "default": null }, "client_uri": { "type": [ "string", "null" ], "default": null }, "data_encryption": { "oneOf": [ { "$ref": "#/components/schemas/DataEncryption" }, { "type": "null" } ], "default": null }, "default_relay_state": { "type": [ "string", "null" ], "default": null }, "description": { "type": [ "string", "null" ], "default": null }, "encrypt_assertion": { "type": [ "boolean", "null" ], "default": null }, "encryption_certificate": { "type": [ "string", "null" ], "default": null }, "entity_id": { "type": "string", "default": "" }, "key_transport": { "oneOf": [ { "$ref": "#/components/schemas/KeyTransport" }, { "type": "null" } ], "default": null }, "logo_uri": { "type": [ "string", "null" ], "default": null }, "name": { "type": "string", "default": "" }, "name_id_format": { "oneOf": [ { "$ref": "#/components/schemas/NameIdFormat" }, { "type": "null" } ], "default": null }, "require_consent": { "type": [ "boolean", "null" ], "description": "Ask the user before releasing attributes. Off by default: SAML SPs\nare enterprise applications an administrator connected.", "default": null }, "require_signed_requests": { "type": [ "boolean", "null" ], "default": null }, "sign_assertion": { "type": [ "boolean", "null" ], "default": null }, "sign_response": { "type": [ "boolean", "null" ], "default": null }, "signing_certificates": { "type": "array", "items": { "type": "string" }, "description": "PEM or base64 DER.", "default": [] }, "slo_binding": { "oneOf": [ { "$ref": "#/components/schemas/SloBinding" }, { "type": "null" } ], "default": null }, "slo_url": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "SamlSpView": { "type": "object", "description": "A registered SP.", "required": [ "client", "saml" ], "properties": { "client": { "$ref": "#/components/schemas/Client" }, "saml": { "$ref": "#/components/schemas/SamlServiceProvider" } } }, "SamlUpstream": { "type": "object", "description": "The SAML side of a `saml` identity provider.", "required": [ "entity_id", "sso_url", "sso_binding", "slo_binding", "signing_certificates", "sign_requests", "want_assertions_signed", "require_encrypted_assertions", "force_authn", "authn_context_class_refs", "allow_unsolicited" ], "properties": { "allow_unsolicited": { "type": "boolean" }, "authn_context_class_refs": { "type": "array", "items": { "type": "string" } }, "entity_id": { "type": "string" }, "force_authn": { "type": "boolean" }, "metadata_error": { "type": [ "string", "null" ], "description": "Why the last refresh failed, until one succeeds." }, "metadata_refreshed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the metadata URL was last read successfully." }, "metadata_url": { "type": [ "string", "null" ] }, "name_id_format": { "oneOf": [ { "$ref": "#/components/schemas/NameIdFormat" }, { "type": "null" } ] }, "require_encrypted_assertions": { "type": "boolean" }, "sign_requests": { "type": "boolean" }, "signing_certificates": { "type": "array", "items": { "type": "string" } }, "slo_binding": { "$ref": "#/components/schemas/SloBinding" }, "slo_url": { "type": [ "string", "null" ] }, "sso_binding": { "$ref": "#/components/schemas/SloBinding" }, "sso_url": { "type": "string" }, "unsolicited_client_id": { "type": [ "string", "null" ] }, "want_assertions_signed": { "type": "boolean" } } }, "SamlUpstreamSettings": { "type": "object", "description": "What an administrator sets for a SAML identity provider.", "properties": { "allow_unsolicited": { "type": "boolean", "description": "Accept unsolicited responses (IdP-initiated sign-in).", "default": false }, "authn_context_class_refs": { "type": "array", "items": { "type": "string" }, "description": "Authentication context classes to ask for (Comparison `exact`).", "default": [] }, "entity_id": { "type": "string", "description": "The IdP's entity ID, the `Issuer` of its messages.", "default": "" }, "force_authn": { "type": "boolean", "description": "Ask the IdP to authenticate the user again (`ForceAuthn`).", "default": false }, "metadata_url": { "type": [ "string", "null" ], "description": "The IdP's metadata URL, refreshed daily: its endpoints and\ncertificates replace the ones above.", "default": null }, "name_id_format": { "oneOf": [ { "$ref": "#/components/schemas/NameIdFormat", "description": "The NameID format to ask for (`NameIDPolicy`); none leaves it to\nthe IdP." }, { "type": "null" } ], "default": null }, "require_encrypted_assertions": { "type": "boolean", "description": "Refuse assertions that are not encrypted (to the tenant's SAML key).", "default": false }, "sign_requests": { "type": "boolean", "description": "Sign `AuthnRequest`s and `LogoutRequest`s with the tenant's SAML key.", "default": true }, "signing_certificates": { "type": "array", "items": { "type": "string" }, "description": "base64 (or PEM) certificates it signs with; several during its\nkey rollover. Nothing unsigned is accepted, so one is required.", "default": [] }, "slo_binding": { "$ref": "#/components/schemas/SloBinding", "default": "redirect" }, "slo_url": { "type": [ "string", "null" ], "description": "Its single logout service; none leaves sign-out local.", "default": null }, "sso_binding": { "$ref": "#/components/schemas/SloBinding", "description": "How `AuthnRequest`s reach it.", "default": "redirect" }, "sso_url": { "type": "string", "description": "Its single sign-on service.", "default": "" }, "unsolicited_client_id": { "type": [ "string", "null" ], "description": "Where an unsolicited sign-in lands: this client's\n`initiate_login_uri`; the account console when unset.", "default": null }, "want_assertions_signed": { "type": "boolean", "description": "The assertion itself must be signed; a signed `Response` around an\nunsigned assertion is refused.", "default": true } }, "additionalProperties": false }, "ScheduledVerification": { "type": "object", "description": "What the `audit_verify` job last established about a chain.", "properties": { "broken_at_seq": { "type": [ "integer", "null" ], "format": "int64", "description": "Where the job found the chain broken, while it stays broken." }, "broken_reason": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_seq": { "type": [ "integer", "null" ], "format": "int64", "description": "The chain is intact up to here." } } }, "ScimToken": { "type": "object", "description": "A bearer token a provisioning system uses against `/scim/v2/{tenant}`.", "required": [ "id", "tenant_id", "name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" } } }, "ScimTokens": { "type": "object", "description": "The tenant's tokens and where a provisioning system should point.", "required": [ "base_url", "tokens" ], "properties": { "base_url": { "type": "string", "description": "`{PUBLIC_URL}/scim/v2/{slug}`." }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ScimToken" } } } }, "Scope": { "type": "object", "required": [ "id", "tenant_id", "name", "claims", "is_default", "created_at", "updated_at" ], "properties": { "claims": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "resource_server_id": { "type": [ "string", "null" ], "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ScopeDoc": { "type": "object", "properties": { "claims": { "type": "array", "items": { "type": "string" }, "default": [] }, "description": { "type": [ "string", "null" ], "default": null }, "is_default": { "type": "boolean", "default": false }, "name": { "type": "string", "default": "" }, "resource_server": { "type": [ "string", "null" ], "description": "Resource server identifier.", "default": null } }, "additionalProperties": false }, "ScopeUpdate": { "type": "object", "description": "Partial scope update; the name is immutable.", "properties": { "claims": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "description": { "type": [ "string", "null" ], "default": null }, "is_default": { "type": [ "boolean", "null" ], "default": null }, "resource_server_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Bind to (or, with `null`, unbind from) a resource server.", "default": null } }, "additionalProperties": false }, "SecretView": { "type": "object", "required": [ "id", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` while current; set once a rotation retired the secret." }, "id": { "type": "string", "format": "uuid" } } }, "Secrets": { "type": "object", "required": [ "clients", "webhooks" ], "properties": { "clients": { "type": "object", "description": "Secrets of clients this import created (public `client_id` → secret).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "identity_providers": { "type": "array", "items": { "type": "string" }, "description": "Identity providers this import created: their client secrets are\nnever exported and must be set by hand." }, "webhooks": { "type": "object", "description": "Signing secrets of webhooks this import created (name → secret).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "SecurityProfile": { "type": "string", "description": "A security profile the client is held to.", "enum": [ "none", "fapi2" ] }, "Sent": { "type": "object", "description": "Where a code went, as told to the user (masked).", "required": [ "sent", "destination" ], "properties": { "destination": { "type": "string" }, "sent": { "type": "boolean" } } }, "ServiceAccountView": { "allOf": [ { "$ref": "#/components/schemas/ClientView" }, { "type": "object", "required": [ "service_account" ], "properties": { "service_account": { "$ref": "#/components/schemas/User" } } } ] }, "SessionPolicy": { "type": "object", "properties": { "absolute_timeout_secs": { "type": "integer", "format": "int64", "default": 43200, "minimum": 0 }, "access_token_ttl_secs": { "type": "integer", "format": "int64", "default": 300, "minimum": 0 }, "id_token_ttl_secs": { "type": "integer", "format": "int64", "default": 300, "minimum": 0 }, "idle_timeout_secs": { "type": "integer", "format": "int64", "default": 1800, "minimum": 0 }, "max_concurrent": { "type": "integer", "format": "int32", "description": "0 = unlimited.", "default": 0, "minimum": 0 }, "refresh_token_ttl_secs": { "type": "integer", "format": "int64", "default": 2592000, "minimum": 0 }, "remember_device_days": { "type": "integer", "format": "int32", "default": 30, "minimum": 0 } } }, "SigningAlg": { "type": "string", "description": "JWS algorithms rIDM can sign with.", "enum": [ "RS256", "RS384", "RS512", "ES256", "EdDSA" ] }, "SigningKey": { "type": "object", "required": [ "id", "tenant_id", "kid", "alg", "public_jwk", "key_version", "status", "not_before", "created_at", "updated_at" ], "properties": { "alg": { "$ref": "#/components/schemas/SigningAlg" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_version": { "type": "integer", "format": "int32", "description": "Master-key generation that encrypted `private_key_enc`." }, "kid": { "type": "string" }, "not_before": { "type": "string", "format": "date-time" }, "public_jwk": { "description": "Public half as a JWK (`kty`, `kid`, `alg`, `use`, and the key parameters)." }, "status": { "$ref": "#/components/schemas/KeyStatus" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Skin": { "type": "string", "description": "The visual skins the UI ships; `design/README.md` describes them.", "enum": [ "signal-v2", "signal", "vault", "registry" ] }, "SloBinding": { "type": "string", "description": "Binding rIDM uses to send an SP its logout messages.", "enum": [ "redirect", "post" ] }, "SmsProviderConfig": { "type": "object", "description": "SMS delivery through any HTTP gateway.", "required": [ "url" ], "properties": { "auth_header": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "SmsSettings": { "type": "object", "required": [ "configured", "auth_header_set" ], "properties": { "auth_header_set": { "type": "boolean" }, "configured": { "type": "boolean" }, "from": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "SmtpConfig": { "type": "object", "description": "Per-tenant SMTP configuration (encrypted at rest).", "required": [ "host", "port", "from" ], "properties": { "from": { "type": "string" }, "host": { "type": "string" }, "password": { "type": [ "string", "null" ] }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "security": { "type": "string", "description": "`starttls` (default), `tls`, or `none`." }, "username": { "type": [ "string", "null" ] } } }, "SsoSession": { "type": "object", "required": [ "id", "tenant_id", "user_id", "auth_time", "amr", "created_at", "last_seen_at", "expires_at", "idle_expires_at" ], "properties": { "acr": { "type": [ "string", "null" ] }, "amr": { "type": "array", "items": { "type": "string" }, "description": "Authentication methods used (`pwd`, `otp`, `hwk`, `mfa`, ...)." }, "auth_time": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "device_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Trusted device this session was opened from, if any." }, "expires_at": { "type": "string", "format": "date-time", "description": "Absolute end of life." }, "id": { "type": "string", "format": "uuid" }, "idle_expires_at": { "type": "string", "format": "date-time", "description": "Sliding end of life." }, "impersonator": { "oneOf": [ { "$ref": "#/components/schemas/Impersonator", "description": "The administrator who opened this session as the user\n(impersonation); the source of the `act` claim." }, { "type": "null" } ] }, "ip": { "type": [ "string", "null" ] }, "last_seen_at": { "type": "string", "format": "date-time" }, "org_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Organization this session acts in; the source of the `org_id` claim." }, "tenant_id": { "type": "string", "format": "uuid" }, "user_agent": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" } } }, "StatusReport": { "type": "object", "required": [ "current_version", "known_versions", "generations", "rows_by_version", "legacy_cipher_rows" ], "properties": { "current_version": { "type": "integer", "format": "int32", "minimum": 0 }, "generations": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationInfo" }, "description": "Every generation: from the environment (`env`) or wrapped by a key\ncustody backend, and whether this node holds it." }, "key_wrapper": { "type": [ "string", "null" ], "description": "The backend new generations are wrapped by (`KEY_WRAPPER`), if any." }, "known_versions": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "legacy_cipher_rows": { "type": "object", "description": "table → (key_version → rows still XChaCha20-Poly1305), only where\nthere are any. The FIPS build's `rotate-master-key` moves them onto\nAES-256-GCM; the standard build still writes it for this release.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "integer", "format": "int32" } }, "propertyNames": { "type": "string" } }, "rows_by_version": { "type": "object", "description": "table → (key_version → rows)", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "integer", "format": "int32" } }, "propertyNames": { "type": "string" } } } }, "Summary": { "type": "object", "required": [ "create", "update", "delete", "unchanged" ], "properties": { "create": { "type": "integer", "minimum": 0 }, "delete": { "type": "integer", "minimum": 0 }, "unchanged": { "type": "integer", "minimum": 0 }, "update": { "type": "integer", "minimum": 0 } } }, "TemplateBody": { "type": "object", "properties": { "body_html": { "type": [ "string", "null" ], "default": null }, "body_text": { "type": "string", "default": "" }, "subject": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "TemplateDoc": { "type": "object", "required": [ "channel", "event", "locale", "body_text" ], "properties": { "body_html": { "type": [ "string", "null" ] }, "body_text": { "type": "string" }, "channel": { "$ref": "#/components/schemas/MessageChannel" }, "event": { "type": "string" }, "locale": { "type": "string" }, "subject": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "TemplateSource": { "type": "string", "enum": [ "override", "builtin" ] }, "TemplateView": { "type": "object", "required": [ "source", "channel", "event", "locale", "body_text" ], "properties": { "body_html": { "type": [ "string", "null" ] }, "body_text": { "type": "string" }, "channel": { "$ref": "#/components/schemas/MessageChannel" }, "event": { "type": "string" }, "locale": { "type": "string" }, "source": { "$ref": "#/components/schemas/TemplateSource" }, "subject": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Templates": { "type": "object", "required": [ "events", "channels", "overrides" ], "properties": { "channels": { "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "type": "string" }, "description": "Events rIDM sends messages for; every one has a built-in English template." }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/MessageTemplate" }, "description": "Tenant overrides by channel, event and locale." } } }, "TemporaryPassword": { "type": "object", "required": [ "temporary_password" ], "properties": { "temporary_password": { "type": "string" } } }, "Tenant": { "type": "object", "required": [ "id", "slug", "display_name", "status", "settings", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_region": { "type": [ "string", "null" ], "description": "The data region the tenant's data lives in (one of `DATA_REGIONS`);\n`None`: the home database. Set when the tenant is created, changed\nonly by `ridm-api move-tenant`." }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "relocating": { "type": "boolean", "description": "A move to another region is under way: the tenant is unavailable\nuntil it ends." }, "settings": { "$ref": "#/components/schemas/TenantSettings" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/TenantStatus" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TenantConfig": { "type": "object", "required": [ "format", "tenant" ], "properties": { "claim_mappers": { "type": "array", "items": { "$ref": "#/components/schemas/MapperDoc" } }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientDoc" } }, "format": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/GroupDoc" } }, "identity_providers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProviderDoc" }, "description": "Upstream providers without their client secrets (set those after an import)." }, "ip_rules": { "type": "array", "items": { "$ref": "#/components/schemas/IpRuleDoc" } }, "message_templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateDoc" } }, "mtls_trust_anchors": { "type": "array", "items": { "$ref": "#/components/schemas/MtlsTrustAnchorDoc" }, "description": "Certificate authorities for `tls_client_auth` clients (RFC 8705)." }, "profile_schema": { "$ref": "#/components/schemas/ProfileSchema" }, "resource_servers": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceServerDoc" } }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDoc" } }, "saml_service_providers": { "type": "array", "items": { "$ref": "#/components/schemas/SamlSpDoc" }, "description": "SAML service providers (`saml` clients), which `clients` leaves out." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeDoc" } }, "tenant": { "$ref": "#/components/schemas/TenantSection" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDoc" } } }, "additionalProperties": false }, "TenantPatch": { "type": "object", "properties": { "display_name": { "type": [ "string", "null" ], "default": null }, "settings": { "description": "Merge patch applied to the current settings document." }, "status": { "oneOf": [ { "$ref": "#/components/schemas/TenantStatus" }, { "type": "null" } ], "default": null } }, "additionalProperties": false }, "TenantSection": { "type": "object", "required": [ "slug", "display_name" ], "properties": { "display_name": { "type": "string" }, "settings": { "$ref": "#/components/schemas/TenantSettings" }, "slug": { "type": "string", "description": "Informational: an import applies to the tenant in the URL." } }, "additionalProperties": false }, "TenantSettings": { "type": "object", "description": "Per-tenant configuration stored as JSONB. Every field has a default so that\nsettings written by older versions keep deserializing.", "properties": { "account": { "$ref": "#/components/schemas/AccountPolicy", "description": "What users may do to their own account from the account console.", "default": { "deletion_retention_days": 30, "personal_token_max_days": 365, "personal_tokens": true, "self_deletion": true } }, "audit": { "$ref": "#/components/schemas/AuditPolicy", "default": { "retention_days": 365 } }, "auth": { "$ref": "#/components/schemas/AuthMethods", "default": { "email_otp": false, "magic_link": false, "passkey": false, "password": true, "sms_otp": false } }, "branding": { "$ref": "#/components/schemas/Branding", "default": { "allow_theme_switch": true, "background_color": null, "contrast_color": null, "custom_css": null, "favicon_url": null, "headline": null, "links": [], "logo_url": null, "mode": "system", "primary_color": null, "skin": "signal-v2", "support_url": null, "tagline": null } }, "captcha": { "$ref": "#/components/schemas/CaptchaPolicy", "default": { "after_failures": 3, "on_registration": true } }, "custom_domain": { "type": [ "string", "null" ], "description": "Custom issuer host (Phase 9.3). `None` means `{PUBLIC_URL}/t/{slug}`.", "default": null }, "dcr": { "$ref": "#/components/schemas/DcrPolicy", "default": { "allowed_grants": [], "mode": "disabled", "require_pkce": true } }, "discovery": { "$ref": "#/components/schemas/DiscoverySettings", "default": { "email_domains": [] } }, "features": { "type": "object", "description": "Feature flags: switches the deployment and its applications consult,\neach on or off for the tenant and optionally per organization. An\napplication reads the ones that are on through the `features` scope.", "default": {}, "additionalProperties": { "$ref": "#/components/schemas/FeatureFlag" }, "propertyNames": { "type": "string" } }, "impersonation": { "$ref": "#/components/schemas/ImpersonationPolicy", "description": "Administrators signing in as users (Phase 12.4), off until enabled.", "default": { "enabled": false, "max_minutes": 60 } }, "keys": { "$ref": "#/components/schemas/KeyPolicy", "default": { "default_alg": "RS256", "retire_overlap_hours": 24, "rotation_interval_days": 90, "rsa_bits": "B2048" } }, "locale": { "$ref": "#/components/schemas/LocaleSettings", "default": { "default": "en", "supported": [ "en" ] } }, "lockout": { "$ref": "#/components/schemas/LockoutPolicy", "default": { "ip_max_failures": 100, "ip_window_minutes": 15, "lock_minutes": 15, "max_failures": 10 } }, "mfa": { "$ref": "#/components/schemas/MfaPolicy", "default": { "mode": "off" } }, "mfa_methods": { "$ref": "#/components/schemas/MfaMethods", "description": "Second factors the tenant offers (passkeys follow `auth.passkey`).", "default": { "email_otp": false, "sms_otp": false, "totp": true } }, "notifications": { "$ref": "#/components/schemas/NotificationPolicy", "default": { "email_changed": true, "mfa_changed": true, "new_device": true, "password_changed": true } }, "password": { "$ref": "#/components/schemas/PasswordPolicy", "default": { "check_breached": false, "history": 5, "max_age_days": null, "max_length": 128, "min_length": 12, "require_digit": false, "require_lowercase": false, "require_symbol": false, "require_uppercase": false } }, "rate_limits": { "$ref": "#/components/schemas/RateLimitPolicy", "description": "Request ceilings on the OAuth and sign-in endpoints.", "default": { "authorize_per_ip": 300, "enabled": true, "flows_per_ip": 600, "tenant_total": 0, "token_per_client": 1200, "token_per_ip": 600, "window_secs": 60 } }, "registration": { "$ref": "#/components/schemas/RegistrationPolicy", "default": { "allowed_email_domains": [], "enabled": false, "privacy_url": null, "require_email_verification": true, "require_terms": false, "terms_url": null } }, "risk": { "$ref": "#/components/schemas/RiskPolicy", "description": "Risk-based adaptive authentication (Phase 12.3), off until enabled.", "default": { "block_at": 100, "enabled": false, "impossible_travel_kmh": 900, "step_up_at": 50, "velocity_max_failures": 10, "velocity_window_minutes": 15, "weights": { "impossible_travel": 60, "new_country": 50, "new_device": 20, "velocity": 40 } } }, "session": { "$ref": "#/components/schemas/SessionPolicy", "default": { "absolute_timeout_secs": 43200, "access_token_ttl_secs": 300, "id_token_ttl_secs": 300, "idle_timeout_secs": 1800, "max_concurrent": 0, "refresh_token_ttl_secs": 2592000, "remember_device_days": 30 } } } }, "TenantStats": { "type": "object", "required": [ "window_days", "from", "to", "days", "logins_total", "failed_total", "previous", "active_sessions", "users", "top_clients", "counts", "attention", "attention_total", "recent" ], "properties": { "active_sessions": { "type": "integer", "format": "int64" }, "attention": { "$ref": "#/components/schemas/Attention" }, "attention_total": { "type": "integer", "format": "int64", "description": "Things needing attention, counted for a badge." }, "counts": { "$ref": "#/components/schemas/Counts" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/DayStats" }, "description": "One entry per day of the window, oldest first, zeros included." }, "failed_total": { "type": "integer", "format": "int64" }, "from": { "type": "string", "format": "date-time" }, "logins_total": { "type": "integer", "format": "int64" }, "previous": { "$ref": "#/components/schemas/WindowTotals", "description": "The same totals for the window before this one." }, "recent": { "type": "array", "items": { "$ref": "#/components/schemas/RecentEvent" }, "description": "The eight newest audit events." }, "to": { "type": "string", "format": "date-time" }, "top_clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientStats" } }, "users": { "$ref": "#/components/schemas/UserStats" }, "window_days": { "type": "integer", "format": "int32", "minimum": 0 } } }, "TenantStatus": { "type": "string", "enum": [ "active", "disabled" ] }, "TestReport": { "type": "object", "description": "What a connection test found.", "required": [ "connected", "bound", "users", "groups" ], "properties": { "bound": { "type": "boolean", "description": "The service account's bind succeeded (true without a bind DN)." }, "connected": { "type": "boolean", "description": "The connection (and TLS) was established." }, "error": { "type": [ "string", "null" ], "description": "What went wrong, when something did." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Up to five group names, when group sync is on." }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/TestUser" }, "description": "Up to five users under the base." } } }, "TestSend": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" } }, "additionalProperties": false }, "TestSendResult": { "type": "object", "required": [ "sender", "to" ], "properties": { "sender": { "type": "string", "description": "Backend that took the message (`smtp`, `http`, `mock`)." }, "to": { "type": "string" } } }, "TestUser": { "type": "object", "description": "A few directory users as a test sees them.", "required": [ "dn" ], "properties": { "dn": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "ThemeMode": { "type": "string", "description": "Light/dark policy: follow each person's device, or always one of them.", "enum": [ "system", "light", "dark" ] }, "TokenEndpointAuthMethod": { "type": "string", "enum": [ "none", "client_secret_basic", "client_secret_post", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth" ] }, "Tokens": { "type": "object", "description": "The user's tokens and the scopes a new one may carry.", "required": [ "tokens", "available_scopes", "enabled", "max_days" ], "properties": { "available_scopes": { "type": "array", "items": { "type": "string" }, "description": "`account` and the admin permissions the user holds." }, "enabled": { "type": "boolean", "description": "The tenant allows personal access tokens." }, "max_days": { "type": "integer", "format": "int32", "description": "The longest a token may live in days; `0` means it may never expire.", "minimum": 0 }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessToken" } } } }, "TrustedDevice": { "type": "object", "required": [ "id", "tenant_id", "user_id", "created_at", "last_seen_at", "expires_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "ip": { "type": [ "string", "null" ] }, "last_seen_at": { "type": "string", "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" }, "user_agent": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" } } }, "User": { "type": "object", "required": [ "id", "tenant_id", "username", "email_verified", "phone_verified", "must_change_password", "status", "attributes", "failed_attempts", "created_at", "updated_at" ], "properties": { "attributes": {}, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ], "description": "The provisioning system's identifier (SCIM `externalId`), unique per tenant." }, "failed_attempts": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "locale": { "type": [ "string", "null" ] }, "locked_until": { "type": [ "string", "null" ], "format": "date-time" }, "must_change_password": { "type": "boolean" }, "org_id": { "type": [ "string", "null" ], "format": "uuid" }, "password_changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "password_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "phone": { "type": [ "string", "null" ] }, "phone_verified": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/UserStatus" }, "tenant_id": { "type": "string", "format": "uuid" }, "terms_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "username": { "type": "string" } } }, "UserDetail": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "required": [ "password", "roles", "effective_roles", "groups" ], "properties": { "effective_roles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "password": { "$ref": "#/components/schemas/PasswordSummary" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } } } ], "description": "The user plus what an admin page shows at a glance." }, "UserGroups": { "type": "object", "required": [ "direct", "effective" ], "properties": { "direct": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "Groups the user is a member of." }, "effective": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "Direct plus their ancestors." } } }, "UserListItem": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "second_step": { "type": [ "string", "null" ], "description": "`passkey`, `totp` or `otp` (email or SMS codes); `null` when none is enrolled." } } } ], "description": "A listed user: the record plus the strongest second step enrolled, so a\nlist can show it without a request per row." }, "UserRoles": { "type": "object", "required": [ "direct", "effective" ], "properties": { "direct": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "Assigned to the user directly." }, "effective": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "Direct plus inherited through groups and composites." } } }, "UserStats": { "type": "object", "required": [ "total", "active", "mfa_enrolled" ], "properties": { "active": { "type": "integer", "format": "int64" }, "mfa_enrolled": { "type": "integer", "format": "int64", "description": "Users holding at least one second factor (TOTP or passkey)." }, "total": { "type": "integer", "format": "int64", "description": "Users that are not soft-deleted." } } }, "UserStatus": { "type": "string", "enum": [ "active", "disabled", "locked", "pending", "deleted" ] }, "UserUpdate": { "type": "object", "properties": { "attributes": {}, "email": { "type": [ "string", "null" ], "default": null }, "email_verified": { "type": [ "boolean", "null" ], "default": null }, "external_id": { "type": [ "string", "null" ], "default": null }, "locale": { "type": [ "string", "null" ], "default": null }, "must_change_password": { "type": [ "boolean", "null" ], "default": null }, "org_id": { "type": [ "string", "null" ], "format": "uuid", "default": null }, "phone": { "type": [ "string", "null" ], "default": null }, "phone_verified": { "type": [ "boolean", "null" ], "default": null }, "status": { "oneOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "type": "null" } ], "default": null }, "username": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "Verification": { "type": "object", "required": [ "checked", "valid" ], "properties": { "broken_at_seq": { "type": [ "integer", "null" ], "format": "int64", "description": "Chain position of the first row whose hash or link does not match." }, "checked": { "type": "integer", "format": "int64", "description": "Rows checked, oldest retained first.", "minimum": 0 }, "first_seq": { "type": [ "integer", "null" ], "format": "int64" }, "last_hash": { "type": [ "string", "null" ], "description": "Hash of the newest row checked (lowercase hex): keep it, and a later\n`ridm audit verify --head` proves an export still ends where it did." }, "last_seq": { "type": [ "integer", "null" ], "format": "int64" }, "reason": { "type": [ "string", "null" ] }, "scheduled": { "oneOf": [ { "$ref": "#/components/schemas/ScheduledVerification", "description": "The daily verification job's progress on this chain." }, { "type": "null" } ] }, "valid": { "type": "boolean" } } }, "Webhook": { "type": "object", "required": [ "id", "tenant_id", "name", "url", "events", "enabled", "headers", "max_attempts", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event names: exact (`user.created`), prefix (`user.*`) or `*`." }, "headers": { "description": "Static headers sent with every delivery." }, "id": { "type": "string", "format": "uuid" }, "max_attempts": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "tenant_id", "webhook_id", "event_id", "event_name", "payload", "status", "attempts", "max_attempts", "next_attempt_at", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "event_id": { "type": "string", "format": "uuid" }, "event_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "last_error": { "type": [ "string", "null" ] }, "last_status": { "type": [ "integer", "null" ], "format": "int32" }, "max_attempts": { "type": "integer", "format": "int32" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "payload": { "description": "The event document as sent." }, "response_snippet": { "type": [ "string", "null" ], "description": "First bytes of the last response body, for diagnostics." }, "status": { "$ref": "#/components/schemas/DeliveryStatus" }, "tenant_id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" } } }, "WebhookDoc": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "events": { "type": "array", "items": { "type": "string" }, "default": [] }, "headers": {}, "max_attempts": { "type": "integer", "format": "int32", "default": 8 }, "name": { "type": "string", "default": "" }, "url": { "type": "string", "default": "" } }, "additionalProperties": false }, "WebhookUpdate": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "default": null }, "events": { "type": [ "array", "null" ], "items": { "type": "string" }, "default": null }, "headers": {}, "max_attempts": { "type": [ "integer", "null" ], "format": "int32", "default": null }, "name": { "type": [ "string", "null" ], "default": null }, "url": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string" } } } ], "description": "A created or rotated webhook with its secret, shown exactly once." }, "WindowTotals": { "type": "object", "description": "The window before this one, for deltas.", "required": [ "logins_total", "failed_total" ], "properties": { "failed_total": { "type": "integer", "format": "int64" }, "logins_total": { "type": "integer", "format": "int64" } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token with the `urn:ridm:admin` audience, issued to a client allowed that audience" } } }, "tags": [ { "name": "auth", "description": "Caller identity and the permission catalogue" }, { "name": "tenants", "description": "Tenants and their settings" }, { "name": "tenant_config", "description": "Tenant configuration as code" }, { "name": "clients", "description": "OAuth / OIDC clients" }, { "name": "users", "description": "Users and everything attached to them" }, { "name": "groups", "description": "Groups, membership and group roles" }, { "name": "organizations", "description": "Organizations within a tenant: membership, email domains and org-scoped role grants" }, { "name": "roles", "description": "Roles, composites and permission grants" }, { "name": "resource_servers", "description": "Resource servers (audiences) and permissions" }, { "name": "scopes", "description": "OAuth scopes" }, { "name": "mappers", "description": "Claim mappers" }, { "name": "keys", "description": "Signing keys and master-key rotation" }, { "name": "saml", "description": "rIDM as a SAML 2.0 identity provider: service providers and the SAML signing keys" }, { "name": "invitations", "description": "Invitations" }, { "name": "messaging", "description": "Email and SMS delivery, templates, delivery log" }, { "name": "audit", "description": "Audit log" }, { "name": "webhooks", "description": "Webhooks and deliveries" }, { "name": "scim", "description": "SCIM provisioning tokens" }, { "name": "ip_rules", "description": "IP allow and deny rules" }, { "name": "mtls", "description": "Certificate authorities for mutual-TLS client authentication" }, { "name": "identity_providers", "description": "Upstream identity providers (OpenID Connect and OAuth 2.0 brokering)" }, { "name": "account", "description": "Self-service account API: the signed-in user's profile, password, contact details, second factors, trusted devices, sessions, consented applications, data export and account deletion" } ] }