{ "openapi": "3.1.0", "info": { "title": "QAuth Account API", "version": "v1-rc.0", "description": "The account API is how a signed-in person manages their own account (ADR-019 Decision 7): the profile, the sign-in methods, the sessions, the security log, the addresses, the connected apps, the notices and deleting the account. The account console calls it from its backend, with the person’s access token.\n\n## Status\n\n- This document is the contract, published before the implementation. The auth server serves two of its operations today, `account.consents.list` and `account.consents.delete`; the others arrive with the account console’s backend. The two served operations still answer errors with the auth server’s general problem document, which may carry `detail` and `errors[].message`; the implementation of this contract narrows them to its problem document. It also narrows what they send beyond that: `client_name` is the name the client registered, which no display rule has checked; the path accepts an id in capital letters; and the deletion’s answer and the errors carry no `Cache-Control: no-store`.\n- `GET /consents` and `DELETE /consents/{id}`, which the hosted UI calls with the session cookie and an `X-CSRF-Token` header, are deprecated aliases of `account.consents.list` and `account.consents.delete`. They are removed when the account console replaces the hosted UI’s consents page.\n- `GET /api/consents` and `DELETE /api/consents/{id}`, deprecated for `/developer/v1-rc.0/consents`, list and revoke a person’s consents with a developer-audience token. A person’s consents move from the developer portal to the account console (ADR-020 §3), so `account.consents.*` is what the console calls. Retiring the developer family’s consent operations is a change of that family’s own contract.\n\n## Tokens\n\n- The callers are backends, such as the account console’s, that hold a person’s access token whose only audience is `urn:qauth:aud:account:v1-rc.0`, sent as a Bearer token or, while the server’s DPoP support is on, a DPoP-bound one. No cookie authenticates a call, and the server sends no CORS headers. Each operation names the audience in `x-qauth-audience`.\n- The token’s subject is an enabled user of the request’s realm, and every operation acts on that user’s own account only. A resource of another account answers `not_found`, as one that does not exist.\n- Each operation names the permission it will need in `x-qauth-permission` and its class in `x-qauth-class`. No scope grants them yet: until the account family defines its scopes, the audience alone admits a token, and a token that lacks a scope an operation requires will get 403 `forbidden`.\n\n## Fresh authentication\n\n- An operation whose `x-qauth-fresh-authentication` is `strongest-factor` needs a sign-in at most 300 seconds old (the token’s `auth_time`) whose `amr` holds the account’s strongest bound factor: `pop` when a passkey is bound, else `otp` when an authenticator app is, else `pwd`.\n- `strongest-factor-or-recovery-code` also accepts a sign-in of the same age that used a recovery code in place of a lost second factor. Only the two halves of a rebind after a lost factor take it (ADR-017 Decision 8): removing a passkey or the authenticator app, and binding a new authenticator app.\n- Otherwise the operation answers 401 `insufficient_user_authentication` (RFC 9470 §3) with the challenge `WWW-Authenticate: Bearer error=\"insufficient_user_authentication\", max_age=\"300\"` when the sign-in is too old, or `max_age=\"0\"` when it is recent but lacks the strongest factor. The problem document carries the same `max_age`. The caller sends the person to the authorization endpoint with that `max_age`, and repeats the call with the new token. That sign-in ends with the account’s strongest bound factor, since a sign-in completes only once the transaction has proved it (ADR-017, the downgrade rule).\n\n## Act-chain tokens\n\n- An act-chain token (RFC 8693 `act`: an admin or an agent acting for the person) never counts as the person’s fresh authentication.\n- An operation whose `x-qauth-act-chain` is `refused` answers an act-chain token with 403 `delegated_token_refused`, before any fresh-authentication check, so a delegated caller never gets a challenge it cannot meet. Every operation that changes a credential, an identifier, the contact address or a linked account refuses one, and so do deleting the account and reporting a sign-in as not the person’s.\n\n## Rules\n\n- Typed data from the auth server’s own records, never HTML. Every string a response carries is an enum, a constant or a bounded value with a pattern. A display value has no markup bracket, no control, format, private-use or unassigned character, no line separator, and no space at either end, and `x-qauth-display` says where it comes from.\n- A request takes no unbounded text: a value the person types, such as a profile value or a passkey’s name, is a bounded display value too. A password is the one exception: it takes any character, appears only in a request (`writeOnly`) and is never shown.\n- Every error is an RFC 9457 problem document (`application/problem+json`) with a stable `code` and a `trace_id`, and no prose: no `detail`, no `instance`, and field errors as reason codes. Each error response lists the codes it may carry in `x-qauth-problem-codes`, a closed list per operation.\n- A list pages by cursor: `limit` (1 to 200, default 50) and `cursor`, the opaque `nextCursor` of the previous page, which is `null` on the last page.\n- An update is a JSON Merge Patch (RFC 7396, `application/merge-patch+json`) sent with `If-Match`, the `ETag` of the resource’s last read. A stale value answers 412 `precondition_failed`, a missing one 428 `precondition_required`.\n- Every answer carries `Cache-Control: no-store`.\n- The security log keeps an entry for 90 days by default, a realm setting. Its `kind` is a closed list, built from QAuth’s events through an allow list.\n\n## Versioning\n\n- The path and the audience carry the major version. Until QAuth 1.0.0 it is a release candidate, `/account/v1-rc.` and `urn:qauth:aud:account:v1-rc.` (today `/account/v1-rc.0`), and nothing about it is promised: a breaking change raises `` for both. The release that ships 1.0.0 serves `/account/v1`.\n- Within a major version, changes are additive only: new operations, new optional request members, new response members, and new values of an extensible set (problem codes, field error reasons, password rejection reasons, profile field types, security notices).\n- A client ignores response members it does not know, and treats a problem code it does not know by its HTTP status. A request with a member the operation does not declare is refused.\n- The published schemas close response objects (`additionalProperties: false`) to describe this version exactly. A later version may add members, so a client must not validate responses strictly against an older schema, and ignores the members it does not know.\n- Removing or renaming a member, changing a type, tightening validation, changing a status code, removing an operation, changing what an operation asks of the token (`x-qauth-fresh-authentication`, `x-qauth-act-chain`) and adding to a closed set, such as the security log’s kinds, need a new major version.\n- A successor major version is served beside the previous one for at least 12 months, and the previous one stays until the next major release of QAuth.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [ { "url": "/", "description": "The auth server’s origin for the realm, the issuer’s. A caller’s backend calls it server to server." } ], "tags": [ { "name": "Profile", "description": "The person’s profile fields and groups." }, { "name": "Sign-in methods", "description": "Password, passkeys, the authenticator app (TOTP) and recovery codes." }, { "name": "Sessions", "description": "Where the person is signed in, and \"sign out everywhere\"." }, { "name": "Security log", "description": "The last 90 days of sign-ins, new devices and security changes, and \"this wasn’t me\"." }, { "name": "Addresses", "description": "The address the account signs in with, and its contact address." }, { "name": "Connected apps", "description": "The apps the person consented to, and their revocation." }, { "name": "Account", "description": "Deleting the account." }, { "name": "Notifications", "description": "The security notices the account receives." } ], "paths": { "/account/v1-rc.0/profile": { "get": { "operationId": "account.profile.get", "summary": "Read the profile", "description": "The profile fields the realm’s profile schema lets the person read, with their values and rules, and the groups the person belongs to.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Profile" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "profile.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The profile.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "example": { "fields": [ { "name": "givenName", "label": "Given name", "type": "text", "required": true, "editable": true, "maxLength": 64, "value": "Ada" }, { "name": "familyName", "label": "Family name", "type": "text", "required": false, "editable": true, "maxLength": 64, "value": "Lovelace" }, { "name": "department", "label": "Department", "help": "Set by your organisation.", "type": "choice", "required": false, "editable": false, "maxLength": 32, "options": [ { "value": "research", "label": "Research" }, { "value": "operations", "label": "Operations" } ], "value": "research" } ], "groups": [ { "id": "0193d6a2-8f41-7b2c-9d3e-4f5a6b7c8d9e", "name": "Research" } ] } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } }, "patch": { "operationId": "account.profile.update", "summary": "Update the profile", "description": "Change the values of fields the person may edit, validated by the realm’s profile schema. It never changes an identifier, the contact address, a verified value or a claim the server sets itself: those fields are refused with `unprocessable_content`.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Profile" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "profile.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The `ETag` of the resource’s last read. A stale value answers 412, a missing one 428.", "schema": { "type": "string", "minLength": 2, "maxLength": 128, "pattern": "^(?:W/)?\"[!#-~]*\"$" }, "example": "\"5d41402abc4b2a76\"" } ], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ProfilePatch" }, "example": { "fields": { "familyName": "King" } } } } }, "responses": { "200": { "description": "The updated profile.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "example": { "fields": [ { "name": "givenName", "label": "Given name", "type": "text", "required": true, "editable": true, "maxLength": 64, "value": "Ada" }, { "name": "familyName", "label": "Family name", "type": "text", "required": false, "editable": true, "maxLength": 64, "value": "King" }, { "name": "department", "label": "Department", "help": "Set by your organisation.", "type": "choice", "required": false, "editable": false, "maxLength": 32, "options": [ { "value": "research", "label": "Research" }, { "value": "operations", "label": "Operations" } ], "value": "research" } ], "groups": [ { "id": "0193d6a2-8f41-7b2c-9d3e-4f5a6b7c8d9e", "name": "Research" } ] } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "412": { "description": "Precondition Failed: `precondition_failed`.", "x-qauth-problem-codes": [ "precondition_failed" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "$ref": "#/components/examples/precondition_failed" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "422": { "description": "Unprocessable Entity: `unprocessable_content`.", "x-qauth-problem-codes": [ "unprocessable_content" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unprocessable_content": { "$ref": "#/components/examples/unprocessable_content" } } } } }, "428": { "description": "Precondition Required: `precondition_required`.", "x-qauth-problem-codes": [ "precondition_required" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_required": { "$ref": "#/components/examples/precondition_required" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/sign-in-methods": { "get": { "operationId": "account.signInMethods.get", "summary": "Read the sign-in methods", "description": "Every way the person can sign in: whether a password is set, how many passkeys, whether TOTP is on, how many recovery codes are left, how many accounts are linked, whether there is a contact address, and the factor a fresh authentication must hold.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "signInMethods.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The sign-in methods.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethods" }, "example": { "password": { "set": true, "changedAt": "2026-08-14T17:02:45Z" }, "passkeys": { "count": 1 }, "totp": { "enabled": false }, "recoveryCodes": { "remaining": 10 }, "linkedAccounts": { "count": 0 }, "hasContactAddress": true, "freshAuthenticationFactor": "pop" } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/password/change": { "post": { "operationId": "account.password.change", "summary": "Change the password", "description": "Replace the password, with the current one. The realm’s password policy and breach list apply to the new one. A wrong current password counts on the account’s failure ladder. Afterwards the account’s other sessions and refresh-token families end, this session stays, and the \"password changed\" notice goes out. An account without a password gets `not_found`: setting a first password is not an account API operation.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "password.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor", "x-qauth-act-chain": "refused", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChangeRequest" }, "example": { "currentPassword": "correct horse battery staple", "newPassword": "quiet lantern under a violet harbour" } } } }, "responses": { "204": { "description": "The password was changed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_current_password`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_current_password" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_current_password": { "$ref": "#/components/examples/invalid_current_password" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "422": { "description": "Unprocessable Entity: `weak_password`.", "x-qauth-problem-codes": [ "weak_password" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "weak_password": { "$ref": "#/components/examples/weak_password" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/passkeys": { "get": { "operationId": "account.passkeys.list", "summary": "List the passkeys", "description": "The passkeys bound to the account, newest first. Adding one is not an account API operation: it runs in the ceremony app on the realm host, whose name is the passkey’s relying-party ID (ADR-020 §1).\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "passkeys.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items a page holds at most.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "description": "Where the page starts: the previous page’s `nextCursor`. Absent for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The `nextCursor` of the previous page. Opaque: a client never builds or changes one." } } ], "responses": { "200": { "description": "A page of passkeys.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyPage" }, "example": { "items": [ { "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", "nickname": "Work laptop", "provider": "Example Passkey Manager", "backedUp": true, "createdAt": "2026-09-30T08:12:00Z", "lastUsedAt": "2026-11-02T09:20:41Z" } ], "nextCursor": null } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_cursor`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_cursor" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/passkeys/{passkeyId}": { "get": { "operationId": "account.passkeys.get", "summary": "Read a passkey", "description": "One passkey, with the `ETag` a rename names.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "passkeys.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "passkeyId", "in": "path", "required": true, "description": "The passkey’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The passkey’s id." }, "example": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b" } ], "responses": { "200": { "description": "The passkey.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" }, "example": { "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", "nickname": "Work laptop", "provider": "Example Passkey Manager", "backedUp": true, "createdAt": "2026-09-30T08:12:00Z", "lastUsedAt": "2026-11-02T09:20:41Z" } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } }, "patch": { "operationId": "account.passkeys.update", "summary": "Rename a passkey", "description": "Change the name the person gave a passkey. A name is no credential, so it needs no fresh authentication (ADR-020 §3); an act-chain token is still refused, as on every change to a credential’s record.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "passkeys.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "refused", "parameters": [ { "name": "passkeyId", "in": "path", "required": true, "description": "The passkey’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The passkey’s id." }, "example": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b" }, { "name": "If-Match", "in": "header", "required": true, "description": "The `ETag` of the resource’s last read. A stale value answers 412, a missing one 428.", "schema": { "type": "string", "minLength": 2, "maxLength": 128, "pattern": "^(?:W/)?\"[!#-~]*\"$" }, "example": "\"5d41402abc4b2a76\"" } ], "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/PasskeyPatch" }, "example": { "nickname": "Laptop (work)" } } } }, "responses": { "200": { "description": "The renamed passkey.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" }, "example": { "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b", "nickname": "Laptop (work)", "provider": "Example Passkey Manager", "backedUp": true, "createdAt": "2026-09-30T08:12:00Z", "lastUsedAt": "2026-11-02T09:20:41Z" } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "412": { "description": "Precondition Failed: `precondition_failed`.", "x-qauth-problem-codes": [ "precondition_failed" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_failed": { "$ref": "#/components/examples/precondition_failed" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "422": { "description": "Unprocessable Entity: `unprocessable_content`.", "x-qauth-problem-codes": [ "unprocessable_content" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unprocessable_content": { "$ref": "#/components/examples/unprocessable_content" } } } } }, "428": { "description": "Precondition Required: `precondition_required`.", "x-qauth-problem-codes": [ "precondition_required" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "precondition_required": { "$ref": "#/components/examples/precondition_required" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } }, "delete": { "operationId": "account.passkeys.delete", "summary": "Remove a passkey", "description": "Unbind a passkey. The last credential that can sign in, such as the only passkey of a passkey-only account, is refused with `last_credential`; the last second factor the realm requires, with `second_factor_required`. A sign-in that used a recovery code in place of a lost passkey may remove it, the first half of a rebind (ADR-017 Decision 8). The \"passkey removed\" notice goes out.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor or a recovery code (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "passkeys.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor-or-recovery-code", "x-qauth-act-chain": "refused", "parameters": [ { "name": "passkeyId", "in": "path", "required": true, "description": "The passkey’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The passkey’s id." }, "example": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b" } ], "responses": { "204": { "description": "The passkey was removed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "409": { "description": "Conflict: `last_credential` or `second_factor_required`.", "x-qauth-problem-codes": [ "last_credential", "second_factor_required" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "last_credential": { "$ref": "#/components/examples/last_credential" }, "second_factor_required": { "$ref": "#/components/examples/second_factor_required" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/totp/enrollment": { "post": { "operationId": "account.totp.enrollment.create", "summary": "Start an authenticator-app enrolment", "description": "Draw a new TOTP secret and return it once, as text and as an `otpauth://` URI. Nothing is bound until the enrolment is confirmed; a new enrolment replaces one not yet confirmed. For the first second factor of a password-only account QAuth also mails an 8-digit code, unless the sign-in already proved that mailbox. An account that has TOTP gets `conflict`; an unclaimed account cannot enrol. A sign-in that used a recovery code in place of a lost second factor may enrol a new one.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor or a recovery code (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "totp.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor-or-recovery-code", "x-qauth-act-chain": "refused", "responses": { "201": { "description": "The started enrolment.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpEnrollment" }, "example": { "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "otpauthUri": "otpauth://totp/Example:ada%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30", "algorithm": "SHA1", "digits": 6, "period": 30, "expiresAt": "2026-11-02T09:40:00Z", "emailCode": "not_required" } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "409": { "description": "Conflict: `conflict`.", "x-qauth-problem-codes": [ "conflict" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "$ref": "#/components/examples/conflict" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/totp/enrollment/confirm": { "post": { "operationId": "account.totp.enrollment.confirm", "summary": "Confirm an authenticator-app enrolment", "description": "Bind the started enrolment’s secret with a first valid code, and the mailed code when the enrolment asked for one. The first second factor of the account also issues the first set of recovery codes, returned once. The \"authenticator app added\" notice goes out. Without a started enrolment, or after it lapsed, the answer is `not_found`.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor or a recovery code (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "totp.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor-or-recovery-code", "x-qauth-act-chain": "refused", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpConfirmRequest" }, "example": { "code": "492039" } } } }, "responses": { "200": { "description": "The bound authenticator app.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpConfirmResult" }, "example": { "enabledAt": "2026-11-02T09:31:12Z", "recoveryCodes": { "codes": [ "ZSOB-UHWE-YYKG-ZBBD", "QCE2-MSJG-H6QW-P7E5", "2YWI-YW62-RZGJ-DGNL", "NBZ6-4WV3-G3L6-7EBC", "EEO7-XCGT-SKJS-YHYE", "QXTK-K2JM-PDOI-RJCN", "CDAM-JSJF-TOPX-44IZ", "VXQJ-TGZN-76DU-DCWD", "6GY4-3WSQ-7IJV-6KL2", "K7CR-KYXS-WQIW-W3HZ" ], "issuedAt": "2026-11-02T09:31:12Z" } } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_code`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_code" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_code": { "$ref": "#/components/examples/invalid_code" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/totp": { "delete": { "operationId": "account.totp.delete", "summary": "Remove the authenticator app", "description": "Unbind TOTP. The last second factor the realm’s policy requires for the account is refused with `second_factor_required`. A sign-in that used a recovery code in place of a lost authenticator app may remove it, the first half of a rebind (ADR-017 Decision 8). The \"authenticator app removed\" notice goes out. An account without TOTP gets `not_found`.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor or a recovery code (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "totp.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor-or-recovery-code", "x-qauth-act-chain": "refused", "responses": { "204": { "description": "The authenticator app was removed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "409": { "description": "Conflict: `second_factor_required`.", "x-qauth-problem-codes": [ "second_factor_required" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "second_factor_required": { "$ref": "#/components/examples/second_factor_required" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/recovery-codes": { "get": { "operationId": "account.recoveryCodes.get", "summary": "Read the recovery codes’ status", "description": "How many recovery codes are left, and when the set was issued. Never the codes.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "recoveryCodes.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The status.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodeStatus" }, "example": { "remaining": 8, "issuedAt": "2026-09-30T08:12:05Z" } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/recovery-codes/regenerate": { "post": { "operationId": "account.recoveryCodes.regenerate", "summary": "Regenerate the recovery codes", "description": "Issue a new set of ten recovery codes, returned once; the old set stops working. An account without a second factor or a passkey has no recovery codes and gets `conflict`. The \"recovery codes regenerated\" notice goes out.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Sign-in methods" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "recoveryCodes.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor", "x-qauth-act-chain": "refused", "responses": { "200": { "description": "The new set.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodeSet" }, "example": { "codes": [ "ZSOB-UHWE-YYKG-ZBBD", "QCE2-MSJG-H6QW-P7E5", "2YWI-YW62-RZGJ-DGNL", "NBZ6-4WV3-G3L6-7EBC", "EEO7-XCGT-SKJS-YHYE", "QXTK-K2JM-PDOI-RJCN", "CDAM-JSJF-TOPX-44IZ", "VXQJ-TGZN-76DU-DCWD", "6GY4-3WSQ-7IJV-6KL2", "K7CR-KYXS-WQIW-W3HZ" ], "issuedAt": "2026-11-02T09:31:12Z" } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "409": { "description": "Conflict: `conflict`.", "x-qauth-problem-codes": [ "conflict" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "$ref": "#/components/examples/conflict" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/sessions": { "get": { "operationId": "account.sessions.list", "summary": "List the sessions", "description": "The account’s browser sessions, most recently used first, each with a device label, an approximate location, when it started and when it was last used. `current` marks the one this request’s token came through.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "sessions.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items a page holds at most.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Where the page starts: the previous page’s `nextCursor`. Absent for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The `nextCursor` of the previous page. Opaque: a client never builds or changes one." } } ], "responses": { "200": { "description": "A page of sessions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPage" }, "example": { "items": [ { "id": "019a2b3c-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "current": true, "createdAt": "2026-11-02T09:20:41Z", "lastSeenAt": "2026-11-02T09:31:00Z", "device": { "label": "Firefox on Linux" }, "location": { "country": "DE", "region": "Berlin", "city": "Berlin" } }, { "id": "019a2a10-77b2-7c31-a4d5-e6f708192a3b", "current": false, "createdAt": "2026-10-28T19:44:10Z", "lastSeenAt": "2026-11-01T21:05:33Z", "device": { "label": "Safari on iPhone" } } ], "nextCursor": null } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_cursor`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_cursor" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/sessions/{sessionId}": { "delete": { "operationId": "account.sessions.delete", "summary": "End a session", "description": "End one session: its cookie stops working, its refresh-token families end, and every app it signed in to gets a back-channel logout. It needs no fresh authentication: ending a session only takes access away.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "sessions.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The session’s id." }, "example": "019a2a10-77b2-7c31-a4d5-e6f708192a3b" } ], "responses": { "204": { "description": "The session ended.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/sessions/end-all": { "post": { "operationId": "account.sessions.endAll", "summary": "Sign out everywhere", "description": "End every session of the account, revoke every refresh-token family, and send a back-channel logout to every app with a session (ADR-017 Decision 8). The session this request’s token came through stays only when `keepCurrent` asks for it.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Sessions" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "sessions.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndAllSessionsRequest" }, "example": { "keepCurrent": true } } } }, "responses": { "204": { "description": "Every session ended.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/security-log": { "get": { "operationId": "account.securityLog.list", "summary": "List the security log", "description": "The account’s security log, newest first: the last 90 days by default, a realm setting. Only the caller’s own entries, and never a raw IP address. A failed sign-in is listed only when its password was right (`second_factor_failed`). `kind` filters by one kind.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Security log" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "securityLog.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items a page holds at most.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "example": 2 }, { "name": "cursor", "in": "query", "required": false, "description": "Where the page starts: the previous page’s `nextCursor`. Absent for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The `nextCursor` of the previous page. Opaque: a client never builds or changes one." } }, { "name": "kind", "in": "query", "required": false, "description": "List only the entries of this kind.", "schema": { "$ref": "#/components/schemas/SecurityLogKind" } } ], "responses": { "200": { "description": "A page of the log.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityLogPage" }, "example": { "items": [ { "id": "019a3f0e-1b2c-7d3e-8f4a-5b6c7d8e9f01", "kind": "new_device", "occurredAt": "2026-11-02T09:20:41Z", "initiator": "user", "delegated": false, "device": { "label": "Firefox on Linux" }, "location": { "country": "DE", "region": "Berlin", "city": "Berlin" }, "reportable": true }, { "id": "019a3e11-4c5d-7e6f-8091-a2b3c4d5e6f7", "kind": "credential_added", "occurredAt": "2026-09-30T08:12:00Z", "initiator": "user", "delegated": false, "device": { "label": "Firefox on Linux" }, "credentialType": "passkey", "reportable": false } ], "nextCursor": "eyJ0IjoxNzkxOTcxOTIwMDAwLCJpZCI6IjAxOWEzZTExIn0" } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_cursor`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_cursor" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/security-log/{entryId}/report": { "post": { "operationId": "account.securityLog.report", "summary": "Report \"this wasn’t me\"", "description": "Report a sign-in the person does not recognise: the session it started ends with its refresh-token families, and the account’s next sign-in asks for a new password (the `update_password` required action). An entry that is not `reportable` gets `conflict`. It refuses an act-chain token: only the person may say a sign-in was not theirs, and the report changes what the next sign-in asks for.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is refused.", "tags": [ "Security log" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "securityLog.report", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "refused", "parameters": [ { "name": "entryId", "in": "path", "required": true, "description": "The entry’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The entry’s id." }, "example": "019a3f0e-1b2c-7d3e-8f4a-5b6c7d8e9f01" } ], "responses": { "204": { "description": "The report was recorded and the session ended.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "409": { "description": "Conflict: `conflict`.", "x-qauth-problem-codes": [ "conflict" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "$ref": "#/components/examples/conflict" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/addresses": { "get": { "operationId": "account.addresses.get", "summary": "Read the addresses", "description": "The address the account signs in with, its contact address, and whether the realm lets the person change the sign-in address.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "addresses.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The addresses.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addresses" }, "example": { "signInAddress": "ada@example.com", "contactAddress": "ada@example.com", "signInAddressChange": "allowed" } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/address-change": { "post": { "operationId": "account.addressChange.create", "summary": "Start an address change", "description": "Start changing the sign-in address, or adding a contact address to an account that signs in without one. An 8-digit code goes to the new address through the capped sender. The answer is the same, in body and timing, whether or not the address belongs to another account; that account’s owner gets the \"account already exists\" notice. A realm that blocks the change answers `disabled_by_realm`. A new start replaces one not yet confirmed.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "addresses.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor", "x-qauth-act-chain": "refused", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressChangeRequest" }, "example": { "use": "sign_in", "address": "ada.lovelace@example.org" } } } }, "responses": { "202": { "description": "The code was sent.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressChange" }, "example": { "use": "sign_in", "expiresAt": "2026-11-02T09:41:12Z" } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused` or `disabled_by_realm`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused", "disabled_by_realm" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" }, "disabled_by_realm": { "$ref": "#/components/examples/disabled_by_realm" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/address-change/confirm": { "post": { "operationId": "account.addressChange.confirm", "summary": "Confirm an address change", "description": "Complete the change with the code mailed to the new address. A new sign-in address replaces the old one in one transaction; the old address gets the \"address changed\" notice, and the account’s other sessions and refresh-token families end. Accounts are never matched or linked by address. Without a started change, or after it lapsed, the answer is `not_found`.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Addresses" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "addresses.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor", "x-qauth-act-chain": "refused", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressChangeConfirmRequest" }, "example": { "code": "40718263" } } } }, "responses": { "200": { "description": "The addresses after the change.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addresses" }, "example": { "signInAddress": "ada.lovelace@example.org", "contactAddress": "ada.lovelace@example.org", "signInAddressChange": "allowed" } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_code`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_code" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_code": { "$ref": "#/components/examples/invalid_code" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused` or `disabled_by_realm`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused", "disabled_by_realm" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" }, "disabled_by_realm": { "$ref": "#/components/examples/disabled_by_realm" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/consents": { "get": { "operationId": "account.consents.list", "summary": "List the connected apps", "description": "The person’s active consents, one per app, by when each was first given, newest first. A new grant to the same app keeps its place in the list.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Connected apps" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "consents.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items a page holds at most.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Where the page starts: the previous page’s `nextCursor`. Absent for the first page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The `nextCursor` of the previous page. Opaque: a client never builds or changes one." } } ], "responses": { "200": { "description": "A page of consents.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentPage" }, "example": { "items": [ { "id": "019a1e5d-2c3b-7a49-b8c7-d6e5f4a3b2c1", "client_id": "https://app.example.com/oauth/client.json", "client_name": "Example Notes", "scopes": [ "openid", "profile", "notes:read" ], "grantedAt": "2026-10-12T15:03:27Z" } ], "nextCursor": null } } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error` or `invalid_cursor`.", "x-qauth-problem-codes": [ "bad_request", "validation_error", "invalid_cursor" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" }, "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/consents/{consentId}": { "delete": { "operationId": "account.consents.delete", "summary": "Disconnect an app", "description": "Revoke one consent, with every refresh token and unredeemed authorization code issued under it. A consent of another account is `not_found`, as one that does not exist. It only takes access away, so it takes an act-chain token: the event names the actor.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Connected apps" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "consents.write", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "parameters": [ { "name": "consentId", "in": "path", "required": true, "description": "The consent’s id.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The consent’s id." }, "example": "019a1e5d-2c3b-7a49-b8c7-d6e5f4a3b2c1" } ], "responses": { "204": { "description": "The consent was revoked.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "404": { "description": "Not Found: `not_found`.", "x-qauth-problem-codes": [ "not_found" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/deletion": { "get": { "operationId": "account.deletion.get", "summary": "Preview the deletion", "description": "Whether the realm lets the person delete the account, and what a deletion removes: sessions, consents, sign-in methods, and the developer clients and API keys the account owns.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "account.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The preview.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionPreview" }, "example": { "allowed": true, "sessions": 2, "consents": 1, "credentials": 3, "clients": 0, "apiKeys": 0 } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } }, "post": { "operationId": "account.deletion.create", "summary": "Delete the account", "description": "Delete the account at once: every row keyed to it, its sessions and refresh-token families, with a back-channel logout to every app for its `sub`. Audit records stay, detached from the account. The \"account deleted\" notice goes to its address, if any. A realm that turned self-deletion off answers `disabled_by_realm`; then only an admin deletes.\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; fresh authentication with the account’s strongest factor (at most 300 seconds old); an act-chain token is refused.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "write", "x-qauth-permission": "account.delete", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "strongest-factor", "x-qauth-act-chain": "refused", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionRequest" }, "example": { "confirmation": "delete-account" } } } }, "responses": { "204": { "description": "The account is deleted. The token no longer names an account.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "description": "Bad Request: `bad_request` or `validation_error`.", "x-qauth-problem-codes": [ "bad_request", "validation_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" }, "validation_error": { "$ref": "#/components/examples/validation_error" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof` or `insufficient_user_authentication`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" }, "insufficient_user_authentication": { "$ref": "#/components/examples/insufficient_user_authentication" } } } } }, "403": { "description": "Forbidden: `forbidden` or `delegated_token_refused` or `disabled_by_realm`.", "x-qauth-problem-codes": [ "forbidden", "delegated_token_refused", "disabled_by_realm" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "delegated_token_refused": { "$ref": "#/components/examples/delegated_token_refused" }, "disabled_by_realm": { "$ref": "#/components/examples/disabled_by_realm" } } } } }, "413": { "description": "Payload Too Large: `content_too_large`.", "x-qauth-problem-codes": [ "content_too_large" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "content_too_large": { "$ref": "#/components/examples/content_too_large" } } } } }, "415": { "description": "Unsupported Media Type: `unsupported_media_type`.", "x-qauth-problem-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/unsupported_media_type" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } }, "/account/v1-rc.0/notification-preferences": { "get": { "operationId": "account.notificationPreferences.get", "summary": "Read the notification preferences", "description": "Every security notice, whether it is mandatory and whether the account receives it, and where notices go. A realm may switch off the notices that are not mandatory (ADR-020 §3).\n\nToken: audience `urn:qauth:aud:account:v1-rc.0`; no fresh authentication; an act-chain token is accepted.", "tags": [ "Notifications" ], "security": [ { "bearerAuth": [] }, { "dpopAuth": [] } ], "x-qauth-stability": "stable", "x-qauth-class": "read", "x-qauth-permission": "notificationPreferences.read", "x-qauth-audience": "urn:qauth:aud:account:v1-rc.0", "x-qauth-fresh-authentication": "none", "x-qauth-act-chain": "accepted", "responses": { "200": { "description": "The notification preferences.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" }, "example": { "delivery": "email", "notices": [ { "notice": "new_device", "mandatory": false, "enabled": true }, { "notice": "password_changed", "mandatory": true, "enabled": true }, { "notice": "credential_disabled", "mandatory": true, "enabled": true }, { "notice": "credential_added", "mandatory": true, "enabled": true }, { "notice": "credential_removed", "mandatory": true, "enabled": true }, { "notice": "recovery_code_used", "mandatory": true, "enabled": true }, { "notice": "recovery_codes_regenerated", "mandatory": true, "enabled": true }, { "notice": "recovery_codes_failed", "mandatory": false, "enabled": true }, { "notice": "send_ceiling_reached", "mandatory": true, "enabled": true }, { "notice": "second_factor_failed", "mandatory": true, "enabled": true }, { "notice": "identifier_changed", "mandatory": true, "enabled": true }, { "notice": "account_deleted", "mandatory": true, "enabled": true } ] } } } }, "400": { "description": "Bad Request: `bad_request`.", "x-qauth-problem-codes": [ "bad_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "bad_request": { "$ref": "#/components/examples/bad_request" } } } } }, "401": { "description": "Unauthorized: `unauthorized` or `access_token_expired` or `invalid_access_token` or `invalid_dpop_proof`.", "x-qauth-problem-codes": [ "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/Challenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" }, "access_token_expired": { "$ref": "#/components/examples/access_token_expired" }, "invalid_access_token": { "$ref": "#/components/examples/invalid_access_token" }, "invalid_dpop_proof": { "$ref": "#/components/examples/invalid_dpop_proof" } } } } }, "403": { "description": "Forbidden: `forbidden`.", "x-qauth-problem-codes": [ "forbidden" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "WWW-Authenticate": { "$ref": "#/components/headers/ScopeChallenge" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } } } } }, "421": { "description": "Misdirected Request: `misdirected_request`.", "x-qauth-problem-codes": [ "misdirected_request" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "misdirected_request": { "$ref": "#/components/examples/misdirected_request" } } } } }, "429": { "description": "Too Many Requests: `too_many_requests`.", "x-qauth-problem-codes": [ "too_many_requests" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "too_many_requests": { "$ref": "#/components/examples/too_many_requests" } } } } }, "500": { "description": "Internal Server Error: `internal_error`.", "x-qauth-problem-codes": [ "internal_error" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "$ref": "#/components/examples/internal_error" } } } } }, "503": { "description": "Service Unavailable: `service_unavailable`.", "x-qauth-problem-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "service_unavailable": { "$ref": "#/components/examples/service_unavailable" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "An access token (RFC 9068) whose only audience is `urn:qauth:aud:account:v1-rc.0` and whose subject is a user of the realm." }, "dpopAuth": { "type": "http", "scheme": "DPoP", "description": "The same access token, bound to a key (RFC 9449), with a `DPoP` proof of the request. Accepted while the server’s DPoP support is on." } }, "headers": { "CacheControl": { "description": "Every answer is `no-store`.", "schema": { "type": "string", "const": "no-store" } }, "ETag": { "description": "The version of the resource. An update sends it back in `If-Match` (RFC 9110 §13.1.1).", "schema": { "type": "string", "minLength": 2, "maxLength": 128, "pattern": "^(?:W/)?\"[!#-~]*\"$" } }, "RetryAfter": { "description": "How many seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 0 } }, "Challenge": { "description": "The challenge (RFC 6750 §3): `Bearer realm=\"OAuth\"` without a token, with `error=\"invalid_token\"` for a refused one, and `Bearer error=\"insufficient_user_authentication\", max_age=\"300\"` (or `max_age=\"0\"`) when fresh authentication is needed (RFC 9470 §3). A DPoP-bound token gets the same under the `DPoP` scheme, and `error=\"invalid_dpop_proof\"` for a refused proof (RFC 9449 §7.1).", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[!-~][ -~]*$" } }, "ScopeChallenge": { "description": "With `forbidden`: the `insufficient_scope` challenge, whose `scope` names the scopes the operation needs (RFC 6750 §3.1). Absent with the other codes.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[!-~][ -~]*$" } } }, "schemas": { "Problem": { "type": "object", "description": "An RFC 9457 problem details document with a stable `code` and a `trace_id`, and no prose: no `detail`, no `instance`, and field errors as reason codes.", "properties": { "type": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[a-z][a-z0-9+.-]*:[!#-;=?-\\[\\]-~]+$", "not": { "type": "string", "pattern": "^(?:javascript|data|vbscript|file|blob):" }, "description": "RFC 9457 §3.1.1: `https://docs.qauth.dev/reference/problem-types/#` followed by the type’s slug. Not for branching." }, "title": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z][A-Za-z -]*$", "description": "The problem type’s title (RFC 9457 §3.1.3), the same in every document with this code. Not for branching, and not for a screen." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated." }, "code": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "x-extensible-enum": [ "bad_request", "validation_error", "invalid_cursor", "invalid_current_password", "invalid_code", "unauthorized", "access_token_expired", "invalid_access_token", "invalid_dpop_proof", "insufficient_user_authentication", "forbidden", "delegated_token_refused", "disabled_by_realm", "not_found", "conflict", "last_credential", "second_factor_required", "precondition_failed", "content_too_large", "unsupported_media_type", "misdirected_request", "unprocessable_content", "weak_password", "precondition_required", "too_many_requests", "internal_error", "service_unavailable" ], "description": "The error. Each error response of an operation lists the codes it may carry (`x-qauth-problem-codes`). A console shows its own text for it, and treats a code it does not know by its HTTP status: a minor release may add codes (ADR-019 Decision 7)." }, "trace_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#-;=?-~]+$", "description": "The id the server logged the request under. A console shows it, so an operator can find the failure." }, "errors": { "type": "array", "description": "With `validation_error` and `unprocessable_content`: each refused field and why.", "items": { "$ref": "#/components/schemas/FieldError" }, "minItems": 1, "maxItems": 64 }, "reasons": { "type": "array", "description": "With `weak_password`: why the new password was refused.", "items": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "x-extensible-enum": [ "too_short", "too_long", "blocklisted", "too_weak", "breached" ], "description": "One reason of the password policy or the breach list." }, "minItems": 1, "maxItems": 8 }, "max_age": { "type": "integer", "minimum": 0, "maximum": 300, "description": "With `insufficient_user_authentication`: the `max_age` of the challenge (RFC 9470 §3), in seconds. Send the person to the authorization endpoint with it, then repeat the call." }, "detail": { "not": {}, "description": "Never sent: no prose." }, "instance": { "not": {}, "description": "Never sent." } }, "required": [ "type", "title", "status", "code", "trace_id" ], "allOf": [ { "if": { "properties": { "code": { "const": "insufficient_user_authentication" } }, "required": [ "code" ] }, "then": { "required": [ "max_age" ] } }, { "if": { "properties": { "code": { "const": "weak_password" } }, "required": [ "code" ] }, "then": { "required": [ "reasons" ] } }, { "if": { "properties": { "code": { "enum": [ "validation_error", "unprocessable_content" ] } }, "required": [ "code" ] }, "then": { "required": [ "errors" ] } } ] }, "FieldError": { "type": "object", "description": "One refused field.", "properties": { "pointer": { "type": "string", "maxLength": 512, "pattern": "^(?:/[A-Za-z0-9_]{1,64}){0,8}$", "description": "An RFC 6901 JSON Pointer into the request body, or `/` for a query or path parameter." }, "reason": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "x-extensible-enum": [ "required", "unknown", "read_only", "too_short", "too_long", "invalid_format", "not_allowed" ], "description": "Why the field was refused. A console shows its own text, or the message the realm’s profile schema gives the field’s validator." } }, "required": [ "pointer", "reason" ], "additionalProperties": false }, "Profile": { "type": "object", "description": "The person’s profile.", "properties": { "fields": { "type": "array", "description": "The fields the realm’s profile schema lets the person read, in its order. Never an identifier, the contact address or a claim the server sets itself (`sub`, `email`, `email_verified` and the others of ADR-020 fork E).", "items": { "$ref": "#/components/schemas/ProfileField" }, "minItems": 0, "maxItems": 64 }, "groups": { "type": "array", "description": "The groups the person belongs to, read only.", "items": { "$ref": "#/components/schemas/Group" }, "minItems": 0, "maxItems": 200 } }, "required": [ "fields", "groups" ], "additionalProperties": false }, "ProfileField": { "type": "object", "description": "One field of the realm’s user profile schema, with the person’s value. Which fields exist, their types, rules and who may edit them are the realm’s (ADR-020, fork E); the contract shows them as a generic list.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-zA-Z0-9]{0,63}$", "description": "The field’s name in the realm’s profile schema, such as `givenName`." }, "label": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "realm", "description": "The field’s label, from the realm’s profile schema." }, "help": { "type": "string", "minLength": 1, "maxLength": 280, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "realm", "description": "The field’s help text, from the realm’s profile schema." }, "type": { "type": "string", "maxLength": 32, "pattern": "^[a-z][a-z0-9_]{0,31}$", "x-extensible-enum": [ "text", "date", "choice" ], "description": "How the console asks for the value: free of markup in one line (`text`), an RFC 3339 full date (`date`), or one of `options` (`choice`). A console shows a type it does not know as read-only text." }, "required": { "type": "boolean", "description": "Whether the realm requires a value." }, "editable": { "type": "boolean", "description": "Whether the person may change it. A field only an admin edits, or one the server verified, is not." }, "verified": { "type": "boolean", "description": "Whether the server verified the value, such as from an upstream provider." }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 255, "description": "The longest value the field accepts." }, "options": { "type": "array", "description": "For `choice`: the values the field accepts.", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_.-]+$", "description": "The value stored when the person picks it." }, "label": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "realm", "description": "The option’s label." } }, "required": [ "value", "label" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 }, "value": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "account", "description": "The value, or `null` when the field is empty." } }, "required": [ "name", "label", "type", "required", "editable", "maxLength", "value" ], "allOf": [ { "if": { "properties": { "type": { "const": "choice" } }, "required": [ "type" ] }, "then": { "required": [ "options" ] } } ], "additionalProperties": false }, "Group": { "type": "object", "description": "A group the person belongs to. Read only: an admin assigns groups.", "properties": { "id": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The group’s id." }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "realm", "description": "The group’s name, as the realm’s admins set it." } }, "required": [ "id", "name" ], "additionalProperties": false }, "ProfilePatch": { "type": "object", "description": "A JSON Merge Patch (RFC 7396) of the profile’s values.", "properties": { "fields": { "type": "object", "description": "New values by field name. `null` empties a field. A field the person may not edit, or one the schema does not hold, is refused with `unprocessable_content`.", "propertyNames": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-zA-Z0-9]{0,63}$" }, "maxProperties": 64, "additionalProperties": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "account", "description": "The new value." } } }, "additionalProperties": false }, "SignInMethods": { "type": "object", "description": "Every way the person can sign in, at a glance.", "properties": { "password": { "type": "object", "properties": { "set": { "type": "boolean", "description": "Whether the account has a password. A passkey-only account has none." }, "changedAt": { "type": [ "string", "null" ], "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When it was last set; `null` without one." } }, "required": [ "set", "changedAt" ], "additionalProperties": false }, "passkeys": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How many passkeys are bound." } }, "required": [ "count" ], "additionalProperties": false }, "totp": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether an authenticator app (TOTP) is bound." } }, "required": [ "enabled" ], "additionalProperties": false }, "recoveryCodes": { "type": "object", "properties": { "remaining": { "type": "integer", "minimum": 0, "maximum": 10, "description": "How many unused recovery codes are left." } }, "required": [ "remaining" ], "additionalProperties": false }, "linkedAccounts": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 100, "description": "How many upstream accounts and wallets are linked. Their lists are the Upstream login and Federation areas’." } }, "required": [ "count" ], "additionalProperties": false }, "hasContactAddress": { "type": "boolean", "description": "Whether the account has a contact address. Without one, security notices go only to the security log." }, "freshAuthenticationFactor": { "type": "string", "enum": [ "pop", "otp", "pwd" ], "description": "The `amr` value a fresh authentication must hold: the account’s strongest bound factor. `pop` with a passkey bound, else `otp` with TOTP, else `pwd` (ADR-017 Decision 8)." } }, "required": [ "password", "passkeys", "totp", "recoveryCodes", "linkedAccounts", "hasContactAddress", "freshAuthenticationFactor" ], "additionalProperties": false }, "PasswordChangeRequest": { "type": "object", "description": "A password change.", "properties": { "currentPassword": { "type": "string", "format": "password", "writeOnly": true, "minLength": 1, "maxLength": 256, "description": "The password the account has now." }, "newPassword": { "type": "string", "format": "password", "writeOnly": true, "minLength": 1, "maxLength": 256, "description": "The new password. The realm’s password policy and breach list apply." } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false }, "Passkey": { "type": "object", "description": "A bound passkey.", "properties": { "id": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The passkey’s id: QAuth’s own, never the WebAuthn credential id." }, "nickname": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "account", "description": "The name the person gave it." }, "provider": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "server", "description": "The authenticator’s maker, from its AAGUID and the server’s list. Absent when unknown." }, "backedUp": { "type": "boolean", "description": "Whether the passkey syncs to other devices (the WebAuthn backup state)." }, "createdAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When it was added." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When it last signed in; `null` if never." } }, "required": [ "id", "nickname", "backedUp", "createdAt", "lastUsedAt" ], "additionalProperties": false }, "PasskeyPage": { "type": "object", "description": "A page of the account’s passkeys, newest first.", "properties": { "items": { "type": "array", "description": "This page’s items, at most `limit`.", "items": { "$ref": "#/components/schemas/Passkey" }, "minItems": 0, "maxItems": 200 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The cursor of the next page; `null` on the last page." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "PasskeyPatch": { "type": "object", "description": "A JSON Merge Patch (RFC 7396) of a passkey: its name.", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "account", "description": "The new name." } }, "additionalProperties": false }, "TotpEnrollment": { "type": "object", "description": "A started authenticator-app enrolment. Nothing is bound until it is confirmed with a first code.", "properties": { "secret": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^[A-Z2-7]{32}$", "description": "The shared secret, base32 (RFC 4648 §6) without padding: 160 bits. Shown once, for typing by hand; never sent again." }, "otpauthUri": { "type": "string", "minLength": 16, "maxLength": 1024, "pattern": "^otpauth://totp/[!#-;=?-~]+$", "description": "The same secret as an `otpauth://totp/` URI with the realm as issuer, for the QR code. Shown once." }, "algorithm": { "type": "string", "const": "SHA1", "description": "Fixed (ADR-020 §3)." }, "digits": { "type": "integer", "const": 6, "description": "Fixed (ADR-020 §3)." }, "period": { "type": "integer", "const": 30, "description": "Seconds per time step. Fixed (ADR-020 §3)." }, "expiresAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the enrolment lapses unless confirmed." }, "emailCode": { "type": "string", "enum": [ "required", "not_required" ], "description": "Whether confirming also needs the 8-digit code QAuth just mailed to the account’s address: the first second factor of a password-only account does, unless the sign-in already proved that mailbox (ADR-017 Decision 8)." } }, "required": [ "secret", "otpauthUri", "algorithm", "digits", "period", "expiresAt", "emailCode" ], "additionalProperties": false }, "TotpConfirmRequest": { "type": "object", "description": "The confirmation of an authenticator-app enrolment.", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^[0-9]{6}$", "description": "The first code the authenticator app shows." }, "emailCode": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^[0-9]{8}$", "description": "The code mailed to the account’s address, when the enrolment asks for one." } }, "required": [ "code" ], "additionalProperties": false }, "TotpConfirmResult": { "type": "object", "description": "A bound authenticator app. `recoveryCodes` is present when it was the account’s first second factor, which issues the first set.", "properties": { "enabledAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the authenticator app was bound." }, "recoveryCodes": { "$ref": "#/components/schemas/RecoveryCodeSet" } }, "required": [ "enabledAt" ], "additionalProperties": false }, "RecoveryCodeSet": { "type": "object", "description": "A new set of recovery codes (ADR-017 Decision 8).", "properties": { "codes": { "type": "array", "description": "The ten codes. Shown once: the server keeps only their hashes.", "items": { "type": "string", "minLength": 19, "maxLength": 19, "pattern": "^[A-Z2-7]{4}(?:-[A-Z2-7]{4}){3}$", "description": "One code: 16 base32 characters (80 bits from a CSPRNG) in four groups. It works once." }, "minItems": 10, "maxItems": 10 }, "issuedAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the set was issued. Every earlier set stopped working then." } }, "required": [ "codes", "issuedAt" ], "additionalProperties": false }, "RecoveryCodeStatus": { "type": "object", "description": "The account’s recovery codes, without the codes.", "properties": { "remaining": { "type": "integer", "minimum": 0, "maximum": 10, "description": "How many unused codes are left." }, "issuedAt": { "type": [ "string", "null" ], "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the current set was issued; `null` without one." } }, "required": [ "remaining", "issuedAt" ], "additionalProperties": false }, "Session": { "type": "object", "description": "A browser session of the account. `location` is absent when unknown.", "properties": { "id": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The session’s id: its record’s, never the cookie value." }, "current": { "type": "boolean", "description": "Whether the token in this request was issued through this session (its `sid`)." }, "createdAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the session started." }, "lastSeenAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When it was last used." }, "device": { "$ref": "#/components/schemas/Device" }, "location": { "$ref": "#/components/schemas/Location" } }, "required": [ "id", "current", "createdAt", "lastSeenAt", "device" ], "additionalProperties": false }, "SessionPage": { "type": "object", "description": "A page of the account’s sessions, most recently used first.", "properties": { "items": { "type": "array", "description": "This page’s items, at most `limit`.", "items": { "$ref": "#/components/schemas/Session" }, "minItems": 0, "maxItems": 200 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The cursor of the next page; `null` on the last page." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "Device": { "type": "object", "description": "The device a session or an entry came from.", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 96, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "declared", "description": "A label from the user agent, such as `Firefox on Linux`. The device declared it." } }, "required": [ "label" ], "additionalProperties": false }, "Location": { "type": "object", "description": "An approximate location from an offline address database. Never the address itself.", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "The country, ISO 3166-1 alpha-2." }, "region": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "server", "description": "The region, when known." }, "city": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "server", "description": "The city, when known." } }, "required": [ "country" ], "additionalProperties": false }, "EndAllSessionsRequest": { "type": "object", "description": "\"Sign out everywhere\".", "properties": { "keepCurrent": { "type": "boolean", "default": false, "description": "Keep the session this request’s token was issued through. Default: end it too." } }, "additionalProperties": false }, "SecurityLogKind": { "type": "string", "enum": [ "signed_in", "new_device", "second_factor_failed", "session_ended", "password_changed", "credential_added", "credential_removed", "credential_disabled", "recovery_code_used", "recovery_codes_regenerated", "recovery_codes_failed", "send_ceiling_reached", "identifier_changed", "account_linked", "account_unlinked", "consent_granted", "consent_revoked" ], "description": "What happened. A closed list: a console may branch on every value. Each kind is built from QAuth events (the event types the docs page names).\n\n- `signed_in`: The person signed in. From `user.signed_in`.\n- `new_device`: The person signed in from a device QAuth had not seen for the account (the device recognition of #689). From `user.new_device_seen`.\n- `second_factor_failed`: A sign-in gave the right password and then a wrong second factor. Only these failed sign-ins are shown: a log of every failed sign-in would tell an attacker which guesses reached the account. From `user.sign_in_failed`.\n- `session_ended`: A session ended: a sign-out, one session ended from the console, or \"sign out everywhere\". From `user.signed_out`.\n- `password_changed`: The account’s password was changed. From `user.password_reset` and `user.password_changed`.\n- `credential_added`: A passkey or an authenticator app (TOTP) was added to the account. From `user.credential_added`.\n- `credential_removed`: A passkey or an authenticator app (TOTP) was removed from the account. From `user.credential_removed`.\n- `credential_disabled`: The password or the authenticator app was disabled after too many wrong attempts (ADR-017 Decision 7). From `user.credential_disabled`.\n- `recovery_code_used`: A recovery code was used in place of a second factor. From `user.recovery_code_used`.\n- `recovery_codes_regenerated`: A new set of recovery codes replaced the old one. From `user.recovery_codes_regenerated`.\n- `recovery_codes_failed`: Recovery codes were tried and refused 100 times (ADR-017 Decision 7). From `user.recovery_codes_failed`.\n- `send_ceiling_reached`: Codes were requested for the account’s address past the per-address send ceiling, and a notice with a reset pass went to it (ADR-017 Decision 7). From `user.send_ceiling_reached`.\n- `identifier_changed`: The address the account signs in with, or its contact address, changed. From `user.identifier_changed`.\n- `account_linked`: A wallet or an upstream account was linked to the account. From `wallet.linked` and `user.upstream_linked`.\n- `account_unlinked`: A wallet or an upstream account was unlinked from the account. From `user.upstream_unlinked`.\n- `consent_granted`: The person let an app access the account. From `consent.granted`.\n- `consent_revoked`: An app’s access to the account was withdrawn. From `consent.revoked`." }, "SecurityLogEntry": { "type": "object", "description": "One entry of the security log. `device`, `location` and `client` are present when the event recorded them; the raw IP address never is.", "properties": { "id": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The entry’s id: the id of the event it was built from." }, "kind": { "$ref": "#/components/schemas/SecurityLogKind" }, "occurredAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When it happened." }, "initiator": { "type": "string", "enum": [ "user", "admin", "policy", "system" ], "description": "Who caused it, as CAEP 1.0 §2 names it: the person, an admin, a realm policy, or QAuth itself (a credential disabled after too many attempts)." }, "delegated": { "type": "boolean", "description": "Whether it came through an act-chain token: an admin or an agent acting for the person (ADR-019 Decision 7)." }, "device": { "$ref": "#/components/schemas/Device" }, "location": { "$ref": "#/components/schemas/Location" }, "client": { "$ref": "#/components/schemas/ClientReference" }, "credentialType": { "type": "string", "enum": [ "password", "passkey", "totp" ], "description": "For `credential_added`, `credential_removed` and `credential_disabled`: which credential." }, "reportable": { "type": "boolean", "description": "Whether \"this wasn’t me\" may be reported on it: a sign-in not yet reported." } }, "required": [ "id", "kind", "occurredAt", "initiator", "delegated", "reportable" ], "allOf": [ { "if": { "properties": { "kind": { "enum": [ "credential_added", "credential_removed", "credential_disabled" ] } }, "required": [ "kind" ] }, "then": { "required": [ "credentialType" ] } } ], "additionalProperties": false }, "SecurityLogPage": { "type": "object", "description": "A page of the security log, newest first.", "properties": { "items": { "type": "array", "description": "This page’s items, at most `limit`.", "items": { "$ref": "#/components/schemas/SecurityLogEntry" }, "minItems": 0, "maxItems": 200 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The cursor of the next page; `null` on the last page." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "ClientReference": { "type": "object", "description": "The app an entry concerns.", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[!#-;=?-\\[\\]-~]+$", "x-qauth-declared": true, "description": "The app’s OAuth `client_id`. A console makes it a link only when it is an `https` URL." }, "client_name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "declared", "description": "The name the app declared about itself." } }, "required": [ "client_id" ], "additionalProperties": false }, "Addresses": { "type": "object", "description": "The account’s identifier and contact address. In 1.0 an identifier is an email address (ADR-017).", "properties": { "signInAddress": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 254, "pattern": "^[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,64}@[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,253}$", "x-qauth-display": "account", "description": "The address the account signs in with; `null` for an account with none, such as a passkey-only account." }, "contactAddress": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 254, "pattern": "^[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,64}@[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,253}$", "x-qauth-display": "account", "description": "Where notices go: the sign-in address, or a contact address added to an account without one; `null` when there is none." }, "signInAddressChange": { "type": "string", "enum": [ "allowed", "blocked" ], "description": "Whether the realm lets the person change the sign-in address (`blocked`: only an admin can)." } }, "required": [ "signInAddress", "contactAddress", "signInAddressChange" ], "additionalProperties": false }, "AddressChangeRequest": { "type": "object", "description": "The start of an address change. An 8-digit code goes to the new address.", "properties": { "use": { "type": "string", "enum": [ "sign_in", "contact" ], "description": "Which address changes: the one the account signs in with, or the contact address of an account that signs in without one." }, "address": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,64}@[^<>@\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0]{1,253}$", "x-qauth-display": "account", "description": "The new address." } }, "required": [ "use", "address" ], "additionalProperties": false }, "AddressChange": { "type": "object", "description": "A started address change. The answer is the same whether or not the new address belongs to another account.", "properties": { "use": { "type": "string", "enum": [ "sign_in", "contact" ], "description": "Which address changes: the one the account signs in with, or the contact address of an account that signs in without one." }, "expiresAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the mailed code lapses." } }, "required": [ "use", "expiresAt" ], "additionalProperties": false }, "AddressChangeConfirmRequest": { "type": "object", "description": "The confirmation of an address change.", "properties": { "code": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^[0-9]{8}$", "description": "The code mailed to the new address." } }, "required": [ "code" ], "additionalProperties": false }, "Consent": { "type": "object", "description": "A connected app: an active consent the person gave. `client_name` is what the app declared about itself, and a console marks it as declared (ADR-019 Decision 6). A later version may add the verified display data the Interaction API shows for a client, as an optional member.", "properties": { "id": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The consent’s id." }, "client_id": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[!#-;=?-\\[\\]-~]+$", "x-qauth-declared": true, "description": "The app’s OAuth `client_id`, which may be a URL (a Client ID Metadata Document client). A console makes it a link only when it is an `https` URL." }, "client_name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0](?:[^<>\\p{C}\\p{Zl}\\p{Zp}\\u115F\\u1160\\u3164\\uFFA0]*[^<>\\p{C}\\p{Z}\\u115F\\u1160\\u3164\\uFFA0])?$", "x-qauth-display": "declared", "description": "The name the app declared about itself." }, "scopes": { "type": "array", "description": "The scopes the person granted.", "items": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!#-;=?-\\[\\]-~]+$", "description": "A scope: an RFC 6749 §3.3 `scope-token` without `<` and `>`, which no QAuth scope holds." }, "minItems": 0, "maxItems": 64 }, "grantedAt": { "type": "string", "format": "date-time", "maxLength": 30, "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,9})?Z$", "description": "When the consent was first given." } }, "required": [ "id", "client_id", "client_name", "scopes", "grantedAt" ], "additionalProperties": false }, "ConsentPage": { "type": "object", "description": "A page of connected apps, by when each consent was first given, newest first.", "properties": { "items": { "type": "array", "description": "This page’s items, at most `limit`.", "items": { "$ref": "#/components/schemas/Consent" }, "minItems": 0, "maxItems": 200 }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The cursor of the next page; `null` on the last page." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "DeletionPreview": { "type": "object", "description": "What deleting the account removes. Audit and event records stay, apart from the account (ADR-018 §3).", "properties": { "allowed": { "type": "boolean", "description": "Whether the realm lets the person delete the account. When it does not, only an admin deletes." }, "sessions": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Sessions that end." }, "consents": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Consents that go, with their refresh tokens." }, "credentials": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Sign-in methods that go: password, passkeys, TOTP, recovery codes." }, "clients": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Developer clients the account owns, which go with it." }, "apiKeys": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "API keys of those clients, which stop working." } }, "required": [ "allowed", "sessions", "consents", "credentials", "clients", "apiKeys" ], "additionalProperties": false }, "DeletionRequest": { "type": "object", "description": "An account deletion.", "properties": { "confirmation": { "type": "string", "const": "delete-account", "description": "Sent only after the person typed the confirmation the console asked for, in their language. The constant keeps a stray call from deleting." } }, "required": [ "confirmation" ], "additionalProperties": false }, "NotificationPreferences": { "type": "object", "description": "The security notices the account receives. Which may be switched off is the realm’s setting (ADR-020 §3); this version reads them.", "properties": { "delivery": { "type": "string", "enum": [ "email", "security_log" ], "description": "Where notices go: the contact address, or only the security log for an account without one." }, "notices": { "type": "array", "description": "Every notice the server sends, in a fixed order.", "items": { "$ref": "#/components/schemas/NoticePreference" }, "minItems": 1, "maxItems": 64 } }, "required": [ "delivery", "notices" ], "additionalProperties": false }, "NoticePreference": { "type": "object", "description": "One security notice.", "properties": { "notice": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "x-extensible-enum": [ "new_device", "password_changed", "credential_disabled", "credential_added", "credential_removed", "recovery_code_used", "recovery_codes_regenerated", "recovery_codes_failed", "send_ceiling_reached", "second_factor_failed", "identifier_changed", "account_deleted" ], "description": "The notice. A minor release may add notices, such as the new-agent-grant notice of ADR-020 §3; a console shows one it does not know by its `mandatory` and `enabled` alone." }, "mandatory": { "type": "boolean", "description": "Whether it always goes out: no setting switches it off." }, "enabled": { "type": "boolean", "description": "Whether the account receives it now." } }, "required": [ "notice", "mandatory", "enabled" ], "additionalProperties": false } }, "examples": { "bad_request": { "summary": "Bad request", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#bad-request", "title": "Bad request", "status": 400, "code": "bad_request", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "validation_error": { "summary": "Validation error", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#validation-error", "title": "Validation error", "status": 400, "code": "validation_error", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60", "errors": [ { "pointer": "/limit", "reason": "too_long" } ] } }, "invalid_cursor": { "summary": "Invalid cursor", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#invalid-cursor", "title": "Invalid cursor", "status": 400, "code": "invalid_cursor", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "invalid_current_password": { "summary": "Invalid current password", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#invalid-current-password", "title": "Invalid current password", "status": 400, "code": "invalid_current_password", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "invalid_code": { "summary": "Invalid code", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#invalid-code", "title": "Invalid code", "status": 400, "code": "invalid_code", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "unauthorized": { "summary": "Unauthorized", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#unauthorized", "title": "Unauthorized", "status": 401, "code": "unauthorized", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "access_token_expired": { "summary": "Access token expired", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#access-token-expired", "title": "Access token expired", "status": 401, "code": "access_token_expired", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "invalid_access_token": { "summary": "Invalid access token", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#invalid-access-token", "title": "Invalid access token", "status": 401, "code": "invalid_access_token", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "invalid_dpop_proof": { "summary": "Invalid DPoP proof", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#invalid-dpop-proof", "title": "Invalid DPoP proof", "status": 401, "code": "invalid_dpop_proof", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "insufficient_user_authentication": { "summary": "Insufficient user authentication", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#insufficient-user-authentication", "title": "Insufficient user authentication", "status": 401, "code": "insufficient_user_authentication", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60", "max_age": 300 } }, "forbidden": { "summary": "Forbidden", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "delegated_token_refused": { "summary": "Delegated token refused", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#delegated-token-refused", "title": "Delegated token refused", "status": 403, "code": "delegated_token_refused", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "disabled_by_realm": { "summary": "Disabled by realm", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#disabled-by-realm", "title": "Disabled by realm", "status": 403, "code": "disabled_by_realm", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "not_found": { "summary": "Not found", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#not-found", "title": "Not found", "status": 404, "code": "not_found", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "conflict": { "summary": "Conflict", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#conflict", "title": "Conflict", "status": 409, "code": "conflict", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "last_credential": { "summary": "Last credential", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#last-credential", "title": "Last credential", "status": 409, "code": "last_credential", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "second_factor_required": { "summary": "Second factor required", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#second-factor-required", "title": "Second factor required", "status": 409, "code": "second_factor_required", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "precondition_failed": { "summary": "Precondition failed", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#precondition-failed", "title": "Precondition failed", "status": 412, "code": "precondition_failed", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "content_too_large": { "summary": "Content too large", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#content-too-large", "title": "Content too large", "status": 413, "code": "content_too_large", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "unsupported_media_type": { "summary": "Unsupported media type", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#unsupported-media-type", "title": "Unsupported media type", "status": 415, "code": "unsupported_media_type", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "misdirected_request": { "summary": "Misdirected request", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#misdirected-request", "title": "Misdirected request", "status": 421, "code": "misdirected_request", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "unprocessable_content": { "summary": "Unprocessable content", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#unprocessable-content", "title": "Unprocessable content", "status": 422, "code": "unprocessable_content", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60", "errors": [ { "pointer": "/fields/department", "reason": "read_only" } ] } }, "weak_password": { "summary": "Weak password", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#weak-password", "title": "Weak password", "status": 422, "code": "weak_password", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60", "reasons": [ "too_short", "breached" ] } }, "precondition_required": { "summary": "Precondition required", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#precondition-required", "title": "Precondition required", "status": 428, "code": "precondition_required", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "too_many_requests": { "summary": "Too many requests", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#too-many-requests", "title": "Too many requests", "status": 429, "code": "too_many_requests", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "internal_error": { "summary": "Internal error", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#internal-error", "title": "Internal error", "status": 500, "code": "internal_error", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } }, "service_unavailable": { "summary": "Service unavailable", "value": { "type": "https://docs.qauth.dev/reference/problem-types/#service-unavailable", "title": "Service unavailable", "status": 503, "code": "service_unavailable", "trace_id": "0b9e2c4f-6a1d-4c3e-9f2a-7d5b8e1c3a60" } } } } }