From 19bb4bd40072a17d401b8c09a918d14030887c7d Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:11:55 +0200
Subject: [PATCH 1/8] feat: add talos docs
---
docs/talos/CLAUDE.md | 109 ++
docs/talos/concepts/architecture.md | 211 +++
docs/talos/concepts/caching.md | 52 +
docs/talos/concepts/credential-types.md | 42 +
docs/talos/concepts/index.md | 17 +
docs/talos/concepts/ip-restrictions.md | 94 ++
docs/talos/concepts/rate-limiting.md | 109 ++
docs/talos/concepts/security-model.md | 131 ++
.../concepts/token-derivation-security.md | 105 ++
docs/talos/concepts/token-format.md | 30 +
docs/talos/index.md | 53 +
docs/talos/integrate/batch-operations.md | 167 ++
docs/talos/integrate/derive-tokens.md | 223 +++
docs/talos/integrate/error-handling.md | 128 ++
docs/talos/integrate/import-keys.md | 233 +++
docs/talos/integrate/index.md | 49 +
docs/talos/integrate/ip-restrictions.md | 253 +++
docs/talos/integrate/issue-and-verify.md | 214 +++
docs/talos/integrate/key-lifecycle.md | 236 +++
docs/talos/integrate/rate-limiting.md | 229 +++
docs/talos/integrate/sdk/curl.md | 270 ++++
docs/talos/integrate/sdk/go.md | 192 +++
docs/talos/integrate/self-revocation.md | 152 ++
docs/talos/operate/benchmarks.md | 136 ++
docs/talos/operate/cache/index.md | 31 +
docs/talos/operate/cache/memory.md | 35 +
docs/talos/operate/cache/redis.md | 40 +
docs/talos/operate/configure.md | 112 ++
docs/talos/operate/database/cockroachdb.md | 102 ++
docs/talos/operate/database/index.md | 30 +
docs/talos/operate/database/migrations.md | 69 +
docs/talos/operate/database/mysql.md | 153 ++
docs/talos/operate/database/postgresql.md | 177 +++
docs/talos/operate/database/sqlite.md | 29 +
docs/talos/operate/deploy/docker.md | 67 +
docs/talos/operate/deploy/edge-proxy.md | 277 ++++
docs/talos/operate/deploy/index.md | 23 +
docs/talos/operate/deploy/kubernetes.md | 117 ++
docs/talos/operate/deploy/separate-planes.md | 83 +
docs/talos/operate/index.md | 47 +
docs/talos/operate/install.md | 70 +
.../talos/operate/monitoring/health-checks.md | 49 +
docs/talos/operate/monitoring/index.md | 12 +
docs/talos/operate/monitoring/metrics.md | 67 +
docs/talos/operate/monitoring/tracing.md | 41 +
docs/talos/operate/multi-tenancy.md | 47 +
docs/talos/operate/secrets.md | 54 +
docs/talos/operate/security-hardening.md | 39 +
docs/talos/operate/tls.md | 18 +
docs/talos/operate/troubleshooting.md | 84 +
docs/talos/quickstart/docker-commercial.md | 119 ++
docs/talos/quickstart/index.md | 216 +++
...e-batch-import-api-keys.RequestSchema.json | 1 +
...ice-batch-import-api-keys.StatusCodes.json | 1 +
...lane-service-batch-import-api-keys.api.mdx | 56 +
...delete-imported-api-key.ParamsDetails.json | 1 +
...delete-imported-api-key.RequestSchema.json | 1 +
...e-delete-imported-api-key.StatusCodes.json | 1 +
...ne-service-delete-imported-api-key.api.mdx | 52 +
...ne-service-derive-token.RequestSchema.json | 1 +
...lane-service-derive-token.StatusCodes.json | 1 +
.../admin-plane-service-derive-token.api.mdx | 52 +
...ce-get-imported-api-key.ParamsDetails.json | 1 +
...ce-get-imported-api-key.RequestSchema.json | 1 +
...vice-get-imported-api-key.StatusCodes.json | 1 +
...plane-service-get-imported-api-key.api.mdx | 52 +
...vice-get-issued-api-key.ParamsDetails.json | 1 +
...vice-get-issued-api-key.RequestSchema.json | 1 +
...ervice-get-issued-api-key.StatusCodes.json | 1 +
...n-plane-service-get-issued-api-key.api.mdx | 52 +
...-plane-service-get-jwks.RequestSchema.json | 1 +
...in-plane-service-get-jwks.StatusCodes.json | 1 +
.../api/admin-plane-service-get-jwks.api.mdx | 43 +
...-service-import-api-key.RequestSchema.json | 1 +
...ne-service-import-api-key.StatusCodes.json | 1 +
...admin-plane-service-import-api-key.api.mdx | 54 +
...e-service-issue-api-key.RequestSchema.json | 1 +
...ane-service-issue-api-key.StatusCodes.json | 1 +
.../admin-plane-service-issue-api-key.api.mdx | 54 +
...-list-imported-api-keys.ParamsDetails.json | 1 +
...-list-imported-api-keys.RequestSchema.json | 1 +
...ce-list-imported-api-keys.StatusCodes.json | 1 +
...ane-service-list-imported-api-keys.api.mdx | 52 +
...ce-list-issued-api-keys.ParamsDetails.json | 1 +
...ce-list-issued-api-keys.RequestSchema.json | 1 +
...vice-list-issued-api-keys.StatusCodes.json | 1 +
...plane-service-list-issued-api-keys.api.mdx | 52 +
...-service-revoke-api-key.ParamsDetails.json | 1 +
...-service-revoke-api-key.RequestSchema.json | 1 +
...ne-service-revoke-api-key.StatusCodes.json | 1 +
...admin-plane-service-revoke-api-key.api.mdx | 53 +
...e-rotate-issued-api-key.ParamsDetails.json | 1 +
...e-rotate-issued-api-key.RequestSchema.json | 1 +
...ice-rotate-issued-api-key.StatusCodes.json | 1 +
...lane-service-rotate-issued-api-key.api.mdx | 63 +
...e-update-issued-api-key.ParamsDetails.json | 1 +
...e-update-issued-api-key.RequestSchema.json | 1 +
...ice-update-issued-api-key.StatusCodes.json | 1 +
...lane-service-update-issued-api-key.api.mdx | 56 +
...e-batch-verify-api-keys.RequestSchema.json | 1 +
...ice-batch-verify-api-keys.StatusCodes.json | 1 +
...lane-service-batch-verify-api-keys.api.mdx | 56 +
...ice-self-revoke-api-key.RequestSchema.json | 1 +
...rvice-self-revoke-api-key.StatusCodes.json | 1 +
...-plane-service-self-revoke-api-key.api.mdx | 57 +
...-service-verify-api-key.RequestSchema.json | 1 +
...ne-service-verify-api-key.StatusCodes.json | 1 +
.../data-plane-service-verify-api-key.api.mdx | 63 +
.../reference/api/ory-talos-api.info.mdx | 44 +
docs/talos/reference/api/sidebar.ts | 120 ++
docs/talos/reference/cli/.gitkeep | 0
.../reference/cli/talos-jwk-generate-ecdsa.md | 60 +
.../reference/cli/talos-jwk-generate-eddsa.md | 61 +
.../reference/cli/talos-jwk-generate-hmac.md | 59 +
.../reference/cli/talos-jwk-generate-rsa.md | 63 +
.../talos/reference/cli/talos-jwk-generate.md | 40 +
docs/talos/reference/cli/talos-jwk-get.md | 36 +
docs/talos/reference/cli/talos-jwk.md | 39 +
.../reference/cli/talos-keys-batch-verify.md | 39 +
.../reference/cli/talos-keys-derive-token.md | 46 +
.../cli/talos-keys-imported-batch-import.md | 44 +
.../cli/talos-keys-imported-delete.md | 38 +
.../reference/cli/talos-keys-imported-get.md | 38 +
.../cli/talos-keys-imported-import.md | 46 +
.../reference/cli/talos-keys-imported-list.md | 42 +
.../cli/talos-keys-imported-revoke.md | 40 +
.../reference/cli/talos-keys-imported.md | 45 +
docs/talos/reference/cli/talos-keys-issue.md | 45 +
.../reference/cli/talos-keys-issued-get.md | 38 +
.../reference/cli/talos-keys-issued-issue.md | 45 +
.../reference/cli/talos-keys-issued-list.md | 42 +
.../reference/cli/talos-keys-issued-rotate.md | 41 +
.../reference/cli/talos-keys-issued-update.md | 44 +
docs/talos/reference/cli/talos-keys-issued.md | 44 +
docs/talos/reference/cli/talos-keys-revoke.md | 39 +
.../reference/cli/talos-keys-self-revoke.md | 44 +
docs/talos/reference/cli/talos-keys-verify.md | 44 +
docs/talos/reference/cli/talos-keys.md | 49 +
.../talos/reference/cli/talos-migrate-down.md | 55 +
.../reference/cli/talos-migrate-force.md | 57 +
.../reference/cli/talos-migrate-status.md | 47 +
docs/talos/reference/cli/talos-migrate-up.md | 63 +
docs/talos/reference/cli/talos-migrate.md | 40 +
docs/talos/reference/cli/talos-proxy.md | 40 +
docs/talos/reference/cli/talos-serve-admin.md | 57 +
docs/talos/reference/cli/talos-serve-check.md | 51 +
docs/talos/reference/cli/talos-serve.md | 55 +
docs/talos/reference/cli/talos.md | 38 +
docs/talos/reference/config.md | 192 +++
docs/talos/reference/error-codes.md | 101 ++
docs/talos/reference/events.md | 79 +
docs/talos/reference/index.md | 21 +
docs/talos/reference/token-format.md | 107 ++
docusaurus.config.ts | 1 +
package-lock.json | 1414 ++++++++++++++++-
package.json | 2 +
src/sidebar.ts | 126 ++
157 files changed, 10430 insertions(+), 41 deletions(-)
create mode 100644 docs/talos/CLAUDE.md
create mode 100644 docs/talos/concepts/architecture.md
create mode 100644 docs/talos/concepts/caching.md
create mode 100644 docs/talos/concepts/credential-types.md
create mode 100644 docs/talos/concepts/index.md
create mode 100644 docs/talos/concepts/ip-restrictions.md
create mode 100644 docs/talos/concepts/rate-limiting.md
create mode 100644 docs/talos/concepts/security-model.md
create mode 100644 docs/talos/concepts/token-derivation-security.md
create mode 100644 docs/talos/concepts/token-format.md
create mode 100644 docs/talos/index.md
create mode 100644 docs/talos/integrate/batch-operations.md
create mode 100644 docs/talos/integrate/derive-tokens.md
create mode 100644 docs/talos/integrate/error-handling.md
create mode 100644 docs/talos/integrate/import-keys.md
create mode 100644 docs/talos/integrate/index.md
create mode 100644 docs/talos/integrate/ip-restrictions.md
create mode 100644 docs/talos/integrate/issue-and-verify.md
create mode 100644 docs/talos/integrate/key-lifecycle.md
create mode 100644 docs/talos/integrate/rate-limiting.md
create mode 100644 docs/talos/integrate/sdk/curl.md
create mode 100644 docs/talos/integrate/sdk/go.md
create mode 100644 docs/talos/integrate/self-revocation.md
create mode 100644 docs/talos/operate/benchmarks.md
create mode 100644 docs/talos/operate/cache/index.md
create mode 100644 docs/talos/operate/cache/memory.md
create mode 100644 docs/talos/operate/cache/redis.md
create mode 100644 docs/talos/operate/configure.md
create mode 100644 docs/talos/operate/database/cockroachdb.md
create mode 100644 docs/talos/operate/database/index.md
create mode 100644 docs/talos/operate/database/migrations.md
create mode 100644 docs/talos/operate/database/mysql.md
create mode 100644 docs/talos/operate/database/postgresql.md
create mode 100644 docs/talos/operate/database/sqlite.md
create mode 100644 docs/talos/operate/deploy/docker.md
create mode 100644 docs/talos/operate/deploy/edge-proxy.md
create mode 100644 docs/talos/operate/deploy/index.md
create mode 100644 docs/talos/operate/deploy/kubernetes.md
create mode 100644 docs/talos/operate/deploy/separate-planes.md
create mode 100644 docs/talos/operate/index.md
create mode 100644 docs/talos/operate/install.md
create mode 100644 docs/talos/operate/monitoring/health-checks.md
create mode 100644 docs/talos/operate/monitoring/index.md
create mode 100644 docs/talos/operate/monitoring/metrics.md
create mode 100644 docs/talos/operate/monitoring/tracing.md
create mode 100644 docs/talos/operate/multi-tenancy.md
create mode 100644 docs/talos/operate/secrets.md
create mode 100644 docs/talos/operate/security-hardening.md
create mode 100644 docs/talos/operate/tls.md
create mode 100644 docs/talos/operate/troubleshooting.md
create mode 100644 docs/talos/quickstart/docker-commercial.md
create mode 100644 docs/talos/quickstart/index.md
create mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
create mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
create mode 100644 docs/talos/reference/api/ory-talos-api.info.mdx
create mode 100644 docs/talos/reference/api/sidebar.ts
create mode 100644 docs/talos/reference/cli/.gitkeep
create mode 100644 docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
create mode 100644 docs/talos/reference/cli/talos-jwk-generate-eddsa.md
create mode 100644 docs/talos/reference/cli/talos-jwk-generate-hmac.md
create mode 100644 docs/talos/reference/cli/talos-jwk-generate-rsa.md
create mode 100644 docs/talos/reference/cli/talos-jwk-generate.md
create mode 100644 docs/talos/reference/cli/talos-jwk-get.md
create mode 100644 docs/talos/reference/cli/talos-jwk.md
create mode 100644 docs/talos/reference/cli/talos-keys-batch-verify.md
create mode 100644 docs/talos/reference/cli/talos-keys-derive-token.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-batch-import.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-delete.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-get.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-import.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-list.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported-revoke.md
create mode 100644 docs/talos/reference/cli/talos-keys-imported.md
create mode 100644 docs/talos/reference/cli/talos-keys-issue.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued-get.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued-issue.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued-list.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued-rotate.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued-update.md
create mode 100644 docs/talos/reference/cli/talos-keys-issued.md
create mode 100644 docs/talos/reference/cli/talos-keys-revoke.md
create mode 100644 docs/talos/reference/cli/talos-keys-self-revoke.md
create mode 100644 docs/talos/reference/cli/talos-keys-verify.md
create mode 100644 docs/talos/reference/cli/talos-keys.md
create mode 100644 docs/talos/reference/cli/talos-migrate-down.md
create mode 100644 docs/talos/reference/cli/talos-migrate-force.md
create mode 100644 docs/talos/reference/cli/talos-migrate-status.md
create mode 100644 docs/talos/reference/cli/talos-migrate-up.md
create mode 100644 docs/talos/reference/cli/talos-migrate.md
create mode 100644 docs/talos/reference/cli/talos-proxy.md
create mode 100644 docs/talos/reference/cli/talos-serve-admin.md
create mode 100644 docs/talos/reference/cli/talos-serve-check.md
create mode 100644 docs/talos/reference/cli/talos-serve.md
create mode 100644 docs/talos/reference/cli/talos.md
create mode 100644 docs/talos/reference/config.md
create mode 100644 docs/talos/reference/error-codes.md
create mode 100644 docs/talos/reference/events.md
create mode 100644 docs/talos/reference/index.md
create mode 100644 docs/talos/reference/token-format.md
diff --git a/docs/talos/CLAUDE.md b/docs/talos/CLAUDE.md
new file mode 100644
index 0000000000..508f82ad40
--- /dev/null
+++ b/docs/talos/CLAUDE.md
@@ -0,0 +1,109 @@
+# Documentation Instructions
+
+## JSON Processing
+
+Use `jq` instead of `python3` for all JSON operations in code examples:
+
+- **Pretty-print:** `| jq .` not `| python3 -m json.tool`
+- **Extract fields:** `| jq -r '.field'` not
+ `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
+
+**Never write curl output to temporary files.** Capture responses in shell variables instead.
+File-based operations fail when `/tmp` doesn't exist or isn't writable.
+
+```bash
+# Good: variable-based
+RESPONSE=$(curl -s -X POST "$URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name": "my-key"}')
+echo "$RESPONSE" | jq .
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+# Bad: file-based
+curl -s ... -o /tmp/response.json
+jq . /tmp/response.json
+KEY_ID=$(jq -r '.key_id' /tmp/response.json)
+rm -f /tmp/response.json
+```
+
+## API Field Documentation
+
+Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or
+enum tables. These are maintained in the canonical references:
+
+- **Field tables** -> auto-generated API reference at `reference/api/*.api.mdx`
+- **Error codes** -> `reference/error-codes.md`
+
+### What belongs in integration guides
+
+- **Workflow and examples**: curl commands, step-by-step instructions, the "how" and "why"
+- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The
+ response includes a `secret` field -- store it securely")
+- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT
+ vs macaroon)
+- **Operational constraints**: limits, cache control headers, retry strategies
+- **Links to reference**: always link to the canonical source for complete field/error details
+
+### What does NOT belong in integration guides
+
+- Full request/response field tables (use API reference link instead)
+- Error code enum tables (use error codes reference link instead)
+- Query parameter tables (use API reference link instead)
+- Revocation reason enum tables (use API reference link instead)
+
+### Link format
+
+**All links MUST be relative links to markdown/mdx files with the file extension.** Never use
+absolute links (starting with `/`) or links without a file extension. Hashbang anchors are allowed
+after the file extension.
+
+- Links to `.md` files: `[text](../reference/error-codes.md#section)`
+- Links to `.api.mdx` files: `[text](../reference/api/admin-plane-service-issue-api-key.api.mdx)`
+- Links to directory index pages: `[text](../operate/cache/index.md)` (never `../operate/cache/`)
+- Links within the same directory: `[text](./sibling-page.md)`
+
+```text
+# Good: relative links with file extensions
+For the complete field reference, see the [IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+For the full list of error codes, see the [error codes reference](../reference/error-codes.md#verification-error-codes).
+
+# Bad: absolute links without file extensions
+For the complete field reference, see the [IssueAPIKey API reference](/reference/api/admin-plane-service-issue-api-key).
+For the full list of error codes, see the [error codes reference](/reference/error-codes#verification-error-codes).
+```
+
+### API reference URL pattern
+
+API reference pages are `.api.mdx` files at `reference/api/{service}-{method}.api.mdx` where:
+
+- `{service}` is `admin-plane-service` or `data-plane-service`
+- `{method}` is the kebab-case method name (e.g., `issue-api-key`, `verify-api-key`)
+
+The API overview page is `reference/api/ory-talos-api.info.mdx`.
+
+### Notes and callouts
+
+Ensure that notes / callouts have two line breaks, or they will get formatted incorrectly.
+
+**Incorrect:**
+
+```md
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by
+external Go modules. :::
+```
+
+```md
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by
+external Go modules. :::
+```
+
+Correct:
+
+```md
+:::note
+
+Internal package The Go client is in an `internal/` package and cannot be imported by external Go
+modules.
+
+:::
+```
diff --git a/docs/talos/concepts/architecture.md b/docs/talos/concepts/architecture.md
new file mode 100644
index 0000000000..8084b4ee50
--- /dev/null
+++ b/docs/talos/concepts/architecture.md
@@ -0,0 +1,211 @@
+---
+title: Architecture
+---
+
+# Architecture
+
+Talos separates API key management into two planes.
+
+## Admin plane
+
+The admin plane handles all write operations: key issuance, rotation, revocation, token derivation,
+and JWKS. It is typically exposed only to internal services.
+
+Endpoints: `/v2/admin/`
+
+## Data plane
+
+The data plane handles high-throughput read operations: key verification, batch verification, and
+self-revocation. It is designed for low-latency edge deployment.
+
+Endpoints: `/v2/admin/apiKeys:verify`, `/v2/admin/apiKeys:batchVerify`, `/v2/apiKeys:selfRevoke`
+
+## Request flow
+
+```
+Client --> Data Plane --> Cache (hit?) --> Database --> Response
+ | ^
+ +-- cache hit ---------------+
+```
+
+1. Client sends credential to `POST /v2/admin/apiKeys:verify`
+2. Talos identifies the credential type (generated, imported, JWT, macaroon)
+3. For generated keys, the UUID is extracted from the token identifier
+4. For imported keys, a tenant-scoped SHA-512/256 hash is computed
+5. Database lookup (or cache hit) returns key metadata
+6. Response includes key status, owner, scopes, and metadata
+
+## Deployment topologies
+
+| Topology | Edition | Description |
+| ------------ | ---------- | --------------------------------------------- |
+| Single-node | OSS | One process serves both planes |
+| Split planes | Commercial | Admin and data planes as separate deployments |
+| Edge proxy | Commercial | Data plane at the edge with local cache |
+
+Both planes share the same database. The data plane can use caching (memory or Redis) to minimize
+database load.
+
+## Ports
+
+| Port | Purpose |
+| ---- | ------------------ |
+| 4420 | HTTP API (default) |
+| 4422 | Prometheus metrics |
+
+## Design philosophy
+
+### Separation of concerns
+
+The system is divided into distinct layers:
+
+- **Admin plane**: Management operations (CRUD for keys, rotation, import, token derivation)
+- **Data plane**: High-throughput verification operations
+- **Persistence layer**: Database abstraction with pluggable drivers
+- **Cache layer**: Performance optimization with multiple backends
+
+This separation allows independent scaling of components, different SLOs for different operations
+(admin targets \<100ms p99, data plane targets \<3ms p99), and clear boundaries between
+responsibilities.
+
+### Production-first design
+
+Inspired by proven systems like SpiceDB and Kubernetes:
+
+- Hard isolation between admin and data operations
+- Comprehensive observability (metrics, traces, logs) built in from the start
+- Graceful degradation and failure handling
+- Zero-downtime deployments
+
+### Performance by default
+
+- Self-contained tokens (JWT/macaroon) enable stateless verification
+- HMAC-SHA256 for fast revocation checks -- not bcrypt, which would limit throughput to ~10 req/sec
+ per core
+- LRU caching for hot paths
+- Minimal allocations in the verification path
+
+## System architecture
+
+```
+Clients (CLI, SDK, HTTP)
+ |
+ v
++----------------------------------+
+| HTTP Server (grpc-gateway) |
+| Port: 4420 |
++----------------------------------+
+ |
+ v
++----------------------------------+
+| Middleware |
+| Logging, Metrics, Tracing |
++----------------------------------+
+ |
+ +-----+----------+
+ | |
+ v v
++-----------+ +-----------+
+| Admin | | Data |
+| Plane | | Plane |
+| <100ms | | <3ms p99 |
++-----------+ +-----------+
+ | |
+ v v
++----------------------------------+
+| Service Layer |
+| Business logic, Validation |
++----------------------------------+
+ |
+ +-----+----------+
+ | |
+ v v
++-----------+ +-----------+
+| Persist. | | Cache |
+| SQLite | | Memory |
+| PG/MySQL | | LRU |
+| CRDB | | Redis |
++-----------+ +-----------+
+```
+
+All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through
+middleware for logging, metrics, and tracing before being routed to the appropriate plane.
+
+## Component overview
+
+### HTTP server
+
+The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both
+planes through a single port, handles CORS and compression, and exposes OpenAPI documentation.
+
+### Service layer
+
+Business logic is split between the admin plane service (key lifecycle, import, token derivation,
+input validation) and the data plane verifier (token parsing, signature verification, revocation
+checking, cache management). The verifier is optimized for the hot path with minimal allocations.
+
+### Persistence
+
+Database access uses sqlc-generated type-safe queries with pluggable drivers:
+
+- **SQLite** -- OSS edition, zero-config, suitable for millions of keys
+- **PostgreSQL** -- production workloads
+- **MySQL** -- production workloads
+- **CockroachDB** -- distributed deployments
+
+Schema changes are managed through versioned migrations using golang-migrate.
+
+### Cache
+
+The cache layer reduces database load on the verification path:
+
+- **Memory LRU** (OSS) -- local to each instance, configurable size limits
+- **Redis** (Commercial) -- distributed, supports cluster and sentinel modes
+- **Hierarchical L1+L2** (Commercial) -- memory for speed, Redis for shared state
+
+### Crypto
+
+Talos supports multiple signing algorithms:
+
+- **Ed25519 (EdDSA)** -- default, fastest signing and smallest keys
+- **RSA-2048/4096 (RS256)** -- legacy compatibility
+- **HMAC-SHA256** -- used for API key revocation checks (\<1ms with constant-time comparison)
+
+### Observability
+
+Built-in instrumentation across three pillars:
+
+- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate
+ counters
+- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and
+ Jaeger exporters
+- **Logging** -- structured JSON logging via slog with correlation IDs and contextual fields
+
+## Scalability
+
+### Small (\<1k RPS)
+
+A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external
+dependencies required.
+
+- OSS edition sufficient
+- 1 CPU, 512MB RAM
+- Cost: $5-10/month
+
+### Medium (10-50k RPS)
+
+Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for
+durability. Redis provides shared caching across data plane instances.
+
+- Commercial edition
+- Auto-scaling for data plane
+- Cost: $100-500/month
+
+### Large (200k+ RPS)
+
+A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis
+cache and PostgreSQL with read replicas and connection pooling. Supports multi-region deployment.
+
+- Commercial edition
+- Regional data plane deployment
+- Cost: $1-5k/month
diff --git a/docs/talos/concepts/caching.md b/docs/talos/concepts/caching.md
new file mode 100644
index 0000000000..0e59a84cad
--- /dev/null
+++ b/docs/talos/concepts/caching.md
@@ -0,0 +1,52 @@
+---
+title: Caching and consistency
+---
+
+# Caching and consistency
+
+Talos can cache verification results to reduce database load and improve latency.
+
+## How it works
+
+When caching is enabled, the first verification request for a key hits the database. Subsequent
+requests within the cache TTL are served from cache without a database lookup.
+
+## Cache types
+
+| Type | Scope | Use case |
+| ------ | ----------- | ----------------------------------- |
+| Memory | Per-process | Single node or per-instance caching |
+| Redis | Shared | Multi-instance deployments |
+
+## Eventual consistency
+
+Caching introduces eventual consistency for revocation:
+
+1. Admin revokes a key via `POST /v2/admin/apiKeys/{id}:revoke`
+2. The revocation takes effect in the database immediately
+3. Cached verification results for that key remain valid until the cache entry expires
+4. After TTL expiry, the next verification hits the database and returns `active: false`
+
+## Cache bypass
+
+To force a database lookup (bypassing cache), include the `Cache-Control: no-cache` header:
+
+```bash
+curl -X POST http://localhost:4420/v2/admin/apiKeys:verify \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d '{"credential": "..."}'
+```
+
+See the [quickstart revocation check](../quickstart/index.md) and the
+[curl SDK reference](../integrate/sdk/curl.md) for tested examples using cache bypass.
+
+## TTL guidelines
+
+| TTL | Trade-off |
+| ----- | ------------------------------------------------- |
+| `1m` | Fast revocation propagation, higher database load |
+| `5m` | Balanced (recommended default) |
+| `30m` | Low database load, slower revocation propagation |
+
+See [Cache operations guide](../operate/cache/index.md) for configuration details.
diff --git a/docs/talos/concepts/credential-types.md b/docs/talos/concepts/credential-types.md
new file mode 100644
index 0000000000..4e33952250
--- /dev/null
+++ b/docs/talos/concepts/credential-types.md
@@ -0,0 +1,42 @@
+---
+title: Credential types
+---
+
+# Credential types
+
+Talos manages four credential types.
+
+## Issued API keys
+
+Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable
+TTL. The key ID (UUID) is embedded in the token for direct database lookup. The full secret is
+returned once at creation.
+
+**Lifecycle**: Issue, rotate, update metadata, revoke.
+
+## Imported API keys
+
+External credentials (Stripe, GitHub, etc.) stored by hash. Any string format accepted. Talos stores
+`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and
+scopes as issued keys.
+
+**Lifecycle**: Import, update metadata, revoke, delete.
+
+## Derived JWTs
+
+Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg`
+field in the JWK (EdDSA or RS256). Can be verified independently using the JWKS endpoint
+(`GET /v2/admin/derivedKeys/jwks.json`). Claims include `key_id`, `actor_id`, scopes, and
+expiration.
+
+## Derived macaroons
+
+Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and
+contextual attenuation.
+
+## Credential routing
+
+When a credential is submitted to `/v2/admin/apiKeys:verify`, Talos identifies the type
+automatically by its format and routes it to the appropriate verification handler. See the
+[credential routing table](../reference/token-format.md#credential-routing) for the full
+format-to-type mapping and lookup methods.
diff --git a/docs/talos/concepts/index.md b/docs/talos/concepts/index.md
new file mode 100644
index 0000000000..6b57a7b962
--- /dev/null
+++ b/docs/talos/concepts/index.md
@@ -0,0 +1,17 @@
+---
+title: Concepts
+---
+
+# Concepts
+
+Core ideas behind Ory Talos.
+
+- [Architecture](architecture.md) — admin plane and data plane separation
+- [Credential types](credential-types.md) — generated keys, imported keys, JWTs, macaroons
+- [Token format](token-format.md) — v1 key format specification
+- [Security model](security-model.md) — cryptographic primitives and tenant isolation
+- [Caching and consistency](caching.md) — verification caching and revocation propagation
+- [Token derivation security](token-derivation-security.md) — stateless verification and revocation
+ semantics
+- [Rate limiting](rate-limiting.md) — rate limit metadata on API keys
+- [IP restrictions](ip-restrictions.md) — CIDR-based access control for API keys
diff --git a/docs/talos/concepts/ip-restrictions.md b/docs/talos/concepts/ip-restrictions.md
new file mode 100644
index 0000000000..6278eaf2a7
--- /dev/null
+++ b/docs/talos/concepts/ip-restrictions.md
@@ -0,0 +1,94 @@
+---
+title: IP restrictions
+description: CIDR-based allowlists that restrict which client IPs can use an API key
+---
+
+# IP restrictions
+
+Talos supports per-key IP restrictions that limit which client IP addresses can use an API key.
+Restrictions are defined as a list of CIDR ranges (for example, `192.168.1.0/24` or
+`2001:db8::/32`). Only requests originating from an IP within the allowlist are accepted. Keys
+without IP restrictions accept traffic from any address.
+
+## How IP restrictions work
+
+IP restriction enforcement has two stages: **IP resolution** and **CIDR matching**.
+
+### IP resolution
+
+When a verification request arrives, Talos captures all IP-related headers from the HTTP request
+into context through middleware. At verification time, the configured **client IP source**
+determines which header to use for extracting the client address. The available sources are:
+
+| Source | Header / value used | Typical use case |
+| ------------------ | ---------------------------- | -------------------------------------- |
+| `REMOTE_ADDR` | TCP remote address | Direct connections without a proxy |
+| `CF_CONNECTING_IP` | `Cf-Connecting-Ip` | Behind Cloudflare |
+| `X_FORWARDED_FOR` | `X-Forwarded-For` (leftmost) | Behind a standard reverse proxy |
+| `X_REAL_IP` | `X-Real-Ip` | Behind NGINX with `proxy_set_header` |
+| `TRUE_CLIENT_IP` | `True-Client-Ip` | Behind Akamai or Cloudflare Enterprise |
+
+If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is
+set once at startup and applies to all verification requests.
+
+### CIDR matching
+
+After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP
+falls within any of the ranges. Both IPv4 and IPv6 CIDR notation are supported (for example,
+`10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32` (IPv4) or `/128` (IPv6) range.
+
+If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification
+fails with error code `VERIFICATION_ERROR_IP_NOT_ALLOWED`.
+
+## Fail-closed behavior
+
+IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for
+example, because the request context does not contain IP metadata -- the verification request is
+denied. This prevents accidental access when header forwarding is misconfigured.
+
+This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking
+legitimate traffic during limiter outages.
+
+## Cache interaction
+
+Cached verification results still contain the key's allowed CIDR list. When a cached key is
+returned, Talos re-evaluates the IP restriction against the **current request's** client IP before
+returning a success response. This means IP restrictions are enforced on every request, regardless
+of whether the result came from cache or the database.
+
+The enforcement sequence is:
+
+1. Resolve the key from cache or database.
+2. Validate key status and expiration.
+3. Resolve the client IP from the current request context.
+4. Check the client IP against the key's allowed CIDR list.
+5. Return the verification result.
+
+## IPv4 and IPv6 support
+
+IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same
+allowlist. Talos parses client addresses using Go's `net.ParseIP`, which handles both formats
+transparently. There is no implicit mapping between IPv4 and IPv6 -- a `10.0.0.0/8` range does not
+match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
+
+## Key concepts
+
+- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is
+ denied. Keys without restrictions accept all IPs.
+- **Per-key granularity** -- each key has its own CIDR list. Keys do not share IP restrictions.
+- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured
+ proxies cannot bypass restrictions.
+- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32`
+ (IPv4) or `/128` (IPv6).
+- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside
+ the key's allowed ranges. See the
+ [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
+- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is
+ served from cache.
+
+## Next steps
+
+- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
+- [Configuration reference](../reference/config.md) -- client IP source and related settings
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
+ error codes including `VERIFICATION_ERROR_IP_NOT_ALLOWED`
diff --git a/docs/talos/concepts/rate-limiting.md b/docs/talos/concepts/rate-limiting.md
new file mode 100644
index 0000000000..76ce2a560a
--- /dev/null
+++ b/docs/talos/concepts/rate-limiting.md
@@ -0,0 +1,109 @@
+---
+title: Rate limiting
+description:
+ Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
+---
+
+# Rate limiting
+
+Talos supports per-key rate limit policies that control how many requests a key can make within a
+time window. A rate limit policy consists of two fields: a **quota** (maximum request count) and a
+**window** (time period in seconds). Keys without a policy are never rate limited.
+
+How enforcement works depends on your edition.
+
+## OSS edition: metadata and headers
+
+In the OSS edition, Talos stores rate limit policies on keys and returns them in verification
+responses. It does not enforce limits itself. Your API gateway or reverse proxy reads the policy
+from the response headers and applies enforcement externally.
+
+This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy,
+NGINX, Kong, or a dedicated service). Verification responses include IETF-format headers that
+gateways can consume directly:
+
+- **`RateLimit-Policy`** -- declares the key's quota and window (e.g., `"default";q=100;w=60`).
+- **`RateLimit`** -- reports remaining quota (e.g., `"default";r=42`).
+
+## Commercial edition: server-side enforcement
+
+The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the
+verification response returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`.
+The HTTP status remains **200** because the verification endpoint always returns a structured
+response — the rate limit status is conveyed through the response body, not the HTTP status code.
+This design allows gateways to distinguish transport errors from application-level rate limiting
+decisions.
+
+### Backends
+
+The commercial edition supports two enforcement backends:
+
+| Backend | Algorithm | Scope | Persistence |
+| -------- | --------- | -------------------------------- | ----------------- |
+| `memory` | GCRA | Single process (not shared) | Lost on restart |
+| `redis` | GCRA | Shared across all connected pods | Survives restarts |
+
+Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate
+limiting without the boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp
+per key and allows requests as long as the average rate stays within the configured quota.
+
+**Memory** is suited for single-node deployments or development. Each process maintains independent
+counters per key, so state is not shared across pods.
+
+**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the
+same Redis instance. State survives process restarts as long as Redis is available.
+
+### Configuration
+
+```yaml
+rate_limit:
+ enabled: true # Hot-reloadable: toggle per-request without restart
+ backend: memory # Requires restart: changes the backend type
+```
+
+- **`rate_limit.enabled`** is checked on every verification request through the config provider. You
+ can toggle it at runtime by editing the config file -- Talos picks up the change automatically.
+- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this
+ value requires a restart because it initializes different infrastructure (in-memory maps vs. Redis
+ connections).
+
+## HTTP response headers
+
+When a key has a rate limit policy, verification responses include IETF draft-compliant headers
+regardless of edition:
+
+| Header | Description | Example |
+| ------------------ | --------------------------------------------------- | ---------------------- |
+| `RateLimit-Policy` | Declares the policy: quota and window | `"default";q=100;w=60` |
+| `RateLimit` | Reports remaining quota | `"default";r=42` |
+| `Retry-After` | Seconds to wait before retrying (only when limited) | `18` |
+
+Gateways and clients can use these headers for both external enforcement (OSS) and client-side
+backoff (Commercial).
+
+## Fail-open behavior
+
+If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos
+**fails open**: verification succeeds but rate limit metadata is omitted from the response. This
+design prevents limiter outages from blocking legitimate traffic.
+
+## Key concepts
+
+- **Per-key isolation** -- each key has its own counter. Keys do not share rate limit budgets.
+- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g.
+ `"60s"`). Both must be set for enforcement to apply.
+- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate
+ limiting.
+- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota
+ (Commercial only). See the
+ [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
+- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification
+ result that is still valid will be returned without consulting the rate limiter.
+
+## Next steps
+
+- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify
+ rate-limited keys, and handle quota exhaustion
+- [Configuration reference](../reference/config.md) -- all `rate_limit.*` settings
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
+ error codes including `VERIFICATION_ERROR_RATE_LIMITED`
diff --git a/docs/talos/concepts/security-model.md b/docs/talos/concepts/security-model.md
new file mode 100644
index 0000000000..94b44e6813
--- /dev/null
+++ b/docs/talos/concepts/security-model.md
@@ -0,0 +1,131 @@
+---
+title: Security model
+---
+
+# Security model
+
+## Cryptographic primitives
+
+| Purpose | Algorithm |
+| -------------------- | ------------------------------------------------------- |
+| API key checksum | HMAC-SHA256 (truncated to 64 bits) |
+| Imported key hashing | SHA-512/256 with tenant salt |
+| JWT signing | EdDSA (Ed25519) or RS256, determined by JWK `alg` field |
+| Macaroon binding | HMAC-SHA256 |
+
+## Secret rotation
+
+Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the old
+one to `retired`. During verification, all secrets are tried in order.
+
+## Tenant isolation
+
+Multi-tenant deployments use Network IDs (NID) for data isolation:
+
+- **Database**: Composite primary keys `(nid, key_id)` prevent cross-tenant access
+- **Token claims**: NID is embedded in derived tokens and validated during verification
+- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different
+ hashes per tenant
+
+## Cache security
+
+Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis
+keys, or memory cache entries. This prevents credential leakage through cache inspection, Redis
+`MONITOR` commands, or memory dumps.
+
+- **Cache key format:** `namespace:nid:sha256(credential)` -- deterministic, no plaintext
+- **Reverse index:** Stores `key_id → sha256(credential)` for invalidation lookups -- no raw secrets
+- **Cached values:** Contain only non-sensitive metadata (status, scopes, owner, expiration)
+
+## Admin/data plane separation
+
+The admin plane (key management) and data plane (verification) can be deployed separately. The admin
+plane should be restricted to internal networks. The data plane can be exposed publicly.
+
+## Key lifecycle
+
+Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is
+irreversible. Expired keys are rejected during verification.
+
+## Why HMAC over bcrypt
+
+Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen
+passwords with ~40-60 bits of entropy). They use intentional slowness (~100ms per hash) to make
+brute-force attacks against weak passwords expensive.
+
+API keys are fundamentally different. They are **cryptographically random** with 128+ bits of
+entropy, making dictionary attacks impossible. The key space of 2^128 (340 undecillion combinations)
+renders brute force infeasible regardless of hashing speed.
+
+HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the
+database. A database breach alone is insufficient to verify candidate keys -- the attacker must also
+compromise the secret. This provides a stronger security boundary than bcrypt, which stores
+everything needed for verification in the database itself.
+
+### Performance comparison
+
+| Metric | bcrypt | HMAC-SHA256 |
+| ----------------------- | ------------ | ---------------- |
+| Single verification | ~100ms | \<1ms |
+| Throughput (per core) | ~10 ops/sec | >100,000 ops/sec |
+| 1,000 verifications | ~100 seconds | \<1 second |
+| 10,000 req/sec capacity | ~1,000 cores | 1 core |
+
+This yields a roughly **1,000x cost reduction** in compute for verification workloads.
+
+### Attack model
+
+**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault).
+Without the secret, they cannot verify any candidate key against the stored hashes.
+
+**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes
+exhaustive search computationally infeasible with current or foreseeable technology.
+
+## Why Ed25519 for token signing
+
+Talos uses Ed25519 (EdDSA over Curve25519) as the default signing algorithm for derived JWTs.
+
+| Property | Ed25519 | RSA-2048 |
+| ------------------ | --------------- | -------------- |
+| Signing speed | ~40,000 ops/sec | ~4,000 ops/sec |
+| Verification speed | ~15,000 ops/sec | ~7,500 ops/sec |
+| Signature size | 64 bytes | 256 bytes |
+| Security level | 128 bits | 112 bits |
+
+Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of
+implementation vulnerabilities (unlike ECDSA P-256, where a weak nonce leaks the private key). It is
+also constant-time by design, providing immunity to timing side-channel attacks.
+
+RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not
+support EdDSA. The signing algorithm is determined by the `alg` field in the JWK configuration.
+
+## Security requirements
+
+For the cryptographic model to hold, the following operational requirements must be met:
+
+1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g.,
+ HashiCorp Vault, AWS Secrets Manager). It must never be stored in the database or committed to
+ version control. Talos supports zero-downtime rotation by maintaining current and retired
+ secrets.
+
+2. **Key entropy** -- API keys must be generated using a cryptographically secure random number
+ generator with at least 128 bits of entropy. Talos generates keys internally; user-provided key
+ material is not accepted for issued keys.
+
+3. **Transport security** -- All communication must use TLS. API key secrets must never appear in
+ URLs, query parameters, or log output.
+
+4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored
+ securely and never exposed through API responses or logs.
+
+## Industry precedent
+
+Major cloud providers use HMAC for API key authentication:
+
+- **AWS** -- HMAC-SHA256 for Signature Version 4 request signing
+- **Google Cloud** -- HMAC keys for Cloud Storage interoperability
+- **Stripe** -- HMAC for API authentication and webhook signature verification
+- **GitHub** -- HMAC-SHA256 for webhook payload signatures
+
+These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and
+verification throughput is a critical operational requirement.
diff --git a/docs/talos/concepts/token-derivation-security.md b/docs/talos/concepts/token-derivation-security.md
new file mode 100644
index 0000000000..3ab52bf2da
--- /dev/null
+++ b/docs/talos/concepts/token-derivation-security.md
@@ -0,0 +1,105 @@
+---
+title: Token derivation security
+description: Stateless verification model and revocation semantics for derived tokens
+---
+
+# Token derivation security
+
+## Overview
+
+Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are
+**stateless capability tokens**: all security constraints are enforced at creation time, and
+verification requires no database access. This design gives predictable sub-millisecond
+verification, zero database load on the hot path, and straightforward edge deployment.
+
+## Creation-time enforcement
+
+When a token is derived via `POST /v2/tokens:derive`, all security constraints are enforced before
+the token is signed:
+
+- **Parent key must be ACTIVE.** A revoked or expired parent key cannot produce new tokens.
+- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than
+ the parent, never more.
+- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the
+ parent key's expiration.
+- **Subject and owner are inherited.** These fields are copied from the parent and cannot be
+ overridden.
+
+If any constraint is violated, the derivation request fails with an appropriate error code. No token
+is issued.
+
+## Verification-time behavior
+
+Verifying a derived token is purely cryptographic. The system checks:
+
+1. **Signature validity** -- the token was signed by a trusted JWK signing key.
+2. **Expiration** -- the `exp` claim has not passed.
+
+There are no database lookups, no parent key status checks, and no scope re-validation against the
+parent. This produces:
+
+- **Low latency.** Verification completes in 1-2 ms compared to 5-10 ms with database round-trips.
+- **Zero database load.** Derived token verification never touches the database.
+- **Edge deployability.** Verification nodes need only the public JWK set, not a database
+ connection.
+- **High availability.** Verification is unaffected by database outages.
+
+## Revocation model
+
+When a parent API key is revoked:
+
+- **New derivations are blocked.** Any attempt to derive from the revoked parent returns an error.
+- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and
+ the token has not expired.
+- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a
+ revocation error.
+
+This behavior is intentional. It provides:
+
+- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full
+ TTL.
+- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions
+ simultaneously.
+- **Graceful degradation.** Downstream systems have time to transition before tokens expire.
+
+## Immediate revocation strategies
+
+If your threat model requires faster invalidation of derived tokens, use one or more of these
+approaches:
+
+- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently
+ with minimal overhead. This is the primary recommended approach.
+- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos.
+ Check the deny list during your application's authorization step.
+- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature
+ verification immediately. This invalidates all derived tokens, not just those from one parent.
+
+## TTL guidelines
+
+| Use case | Recommended TTL | Rationale |
+| -------------------------- | ----------------------- | -------------------------------------------------- |
+| User sessions (web/mobile) | 15-60 min | Balances user experience with security exposure |
+| Service-to-service auth | 5-15 min | Services re-derive easily; minimal exposure window |
+| Sensitive operations | 1-5 min | Limits damage from token theft |
+| Long-running batch jobs | Use parent key directly | Avoids re-derivation during long processes |
+
+Short TTLs are the simplest and most effective control. When combined with the stateless
+verification model, they give security properties equivalent to stateful parent-status checks
+without the latency or availability cost.
+
+## Security properties
+
+Derived tokens are capability tokens with time-bounded authority:
+
+1. **All constraints enforced at creation.** The token can only be issued if the parent passes all
+ checks.
+2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered
+ with.
+3. **Time-bounded exposure.** Short TTLs limit the window in which a compromised token is useful.
+4. **Immutable claims.** Subject, owner, scopes, and expiry are sealed in the token.
+5. **No privilege escalation.** Scopes can never exceed the parent's scopes at creation time.
+
+## Next steps
+
+- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
+- [Derive tokens](../integrate/derive-tokens.md) -- integration guide for the token derivation API
diff --git a/docs/talos/concepts/token-format.md b/docs/talos/concepts/token-format.md
new file mode 100644
index 0000000000..9651a6f663
--- /dev/null
+++ b/docs/talos/concepts/token-format.md
@@ -0,0 +1,30 @@
+---
+title: Token format
+---
+
+# Token format
+
+Issued API keys follow a structured v1 format:
+
+```
+{prefix}_v1_{identifier}_{checksum}
+```
+
+## Components
+
+| Part | Length | Description |
+| ---------- | ----------- | ---------------------------------------- |
+| Prefix | 1-8 chars | Configurable label (e.g., `prod`, `dev`) |
+| `v1` | 2 chars | Format version |
+| Identifier | ~32 chars | Base58-encoded timestamp + UUID |
+| Checksum | 10-11 chars | HMAC-SHA256, truncated, Base58 |
+
+## How it works
+
+The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used
+for database lookup. The checksum is HMAC-SHA256 over the payload, enabling tamper detection.
+
+During verification, all configured secrets (current + retired) are tried, supporting zero-downtime
+secret rotation.
+
+See [Token format reference](../reference/token-format.md) for the full specification.
diff --git a/docs/talos/index.md b/docs/talos/index.md
new file mode 100644
index 0000000000..8e8d94f9ba
--- /dev/null
+++ b/docs/talos/index.md
@@ -0,0 +1,53 @@
+---
+title: Ory Talos
+---
+
+# Ory Talos
+
+Ory Talos is a high-performance API key management service. It handles the full lifecycle of API
+credentials: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
+macaroon), and revoking access.
+
+Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations**
+(verify, self-revoke) so you can scale and secure each path independently.
+
+## Choose your path
+
+### I want to integrate Talos into my application
+
+You're a developer building an application that needs API key authentication. Start here:
+
+- **[Quickstart](./quickstart/index.md)** — issue and verify your first API key in 5 minutes
+- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying,
+ importing keys, and deriving tokens
+- **[Error handling](./integrate/error-handling.md)** — error codes and retry strategies
+
+### I want to run Talos in production
+
+You're a platform engineer responsible for deploying and operating Talos. Start here:
+
+- **[Install](./operate/install.md)** — binary install or build from source
+- **[Configure](./operate/configure.md)** — configuration file, environment variables, and
+ hot-reload behavior
+- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane
+ topologies
+- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and
+ health endpoints
+
+## Editions
+
+**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key
+lifecycle, token derivation, and CLI.
+
+**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed
+caching (Redis, in-memory), edge proxy nodes, and the admin UI. Pages that cover commercial-only
+features are marked with a "Commercial" badge.
+
+## Learn more
+
+- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching
+ behavior
+- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint
+ documentation
+- **[CLI reference](./reference/index.md)** — command-line tool documentation
+- **[Configuration reference](./reference/config.md)** — all configuration keys and their defaults
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.md
new file mode 100644
index 0000000000..77012e937d
--- /dev/null
+++ b/docs/talos/integrate/batch-operations.md
@@ -0,0 +1,167 @@
+---
+title: Batch operations
+description: Verify and import multiple credentials in a single request
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Batch operations
+
+Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in
+parallel and return per-item results.
+
+
+
+
+First, issue two keys to use in batch operations:
+
+
+
+
+
+
+```bash
+KEY1=$(talos keys issue "batch-key-1" \
+ --actor user_1 --scopes "read" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
+
+KEY2=$(talos keys issue "batch-key-2" \
+ --actor user_2 --scopes "write" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
+
+echo "export KEY1=$KEY1" >> "$DOCTEST_ENV_FILE"
+echo "export KEY2=$KEY2" >> "$DOCTEST_ENV_FILE"
+echo "Keys issued"
+```
+
+
+
+
+```bash
+KEY1=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"batch-key-1","actor_id":"user_1","scopes":["read"]}' | \
+ jq -r '.secret')
+
+KEY2=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"batch-key-2","actor_id":"user_2","scopes":["write"]}' | \
+ jq -r '.secret')
+
+echo "export KEY1=$KEY1" >> "$DOCTEST_ENV_FILE"
+echo "export KEY2=$KEY2" >> "$DOCTEST_ENV_FILE"
+echo "Keys issued"
+```
+
+
+
+
+## Batch verify
+
+Verify up to 100 credentials in a single request:
+
+
+
+
+
+
+```bash
+talos keys batch-verify "$KEY1" "$KEY2" "invalid-key-for-testing" \
+ --format json \
+ -e "$TALOS_URL" | jq .
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"requests\": [
+ {\"credential\": \"$KEY1\"},
+ {\"credential\": \"$KEY2\"},
+ {\"credential\": \"invalid-key-for-testing\"}
+ ]
+ }" | jq .
+```
+
+
+
+
+### Response format
+
+The response contains a `results` array. Each element has the same fields as a single
+[verify response](./issue-and-verify.md#verification-response). Results are returned in the same
+order as the requests.
+
+Invalid credentials return `active: false` with an `error_code` — they do not cause the batch
+request to fail.
+
+### Limits
+
+| Constraint | Value |
+| ------------------------------- | ----- |
+| Maximum credentials per request | 100 |
+| Minimum credentials per request | 1 |
+
+## Batch import
+
+Import up to 1000 keys in a single request:
+
+
+
+
+
+
+```bash
+talos keys imported batch-import --file - -e "$TALOS_URL" <<'JSON'
+[
+ {"raw_key": "legacy_key_aaa", "name": "Legacy Key A", "actor_id": "migration"},
+ {"raw_key": "legacy_key_bbb", "name": "Legacy Key B", "actor_id": "migration"},
+ {"raw_key": "legacy_key_ccc", "name": "Legacy Key C", "actor_id": "migration", "scopes": ["read"]}
+]
+JSON
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "requests": [
+ {"raw_key": "legacy_key_aaa", "name": "Legacy Key A", "actor_id": "migration"},
+ {"raw_key": "legacy_key_bbb", "name": "Legacy Key B", "actor_id": "migration"},
+ {"raw_key": "legacy_key_ccc", "name": "Legacy Key C", "actor_id": "migration", "scopes": ["read"]}
+ ]
+ }' | jq .
+```
+
+
+
+
+### Response format
+
+The response includes a `results` array with per-item outcomes, plus `success_count` and
+`failure_count` counters. The HTTP response is `200 OK` if at least one key succeeds. Check
+`failure_count` and individual `error_code` fields to detect partial failures.
+
+For the complete field reference, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx).
+For batch import error codes, see the
+[error codes reference](../reference/error-codes.md#batch-import-error-codes).
+
+### Limits
+
+| Constraint | Value |
+| ------------------------ | ----- |
+| Maximum keys per request | 1000 |
+
+## Next steps
+
+- [Import keys](import-keys.md) — single key import with full field reference
+- [Issue and verify](issue-and-verify.md) — create and verify individual keys
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.md
new file mode 100644
index 0000000000..733eb3d91b
--- /dev/null
+++ b/docs/talos/integrate/derive-tokens.md
@@ -0,0 +1,223 @@
+---
+title: Derive tokens
+description: Mint short-lived JWT or macaroon tokens from API keys
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Derive tokens
+
+Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived
+tokens when you need:
+
+- **Browser-safe credentials** — JWTs can be verified client-side without hitting the server.
+- **Temporary access** — grant time-limited access with a subset of the parent key's scopes.
+- **Custom claims** — embed application-specific data in the token.
+
+Derived tokens inherit permissions from the parent API key and can be verified on the same data
+plane endpoint.
+
+
+
+
+First, issue a parent key for token derivation:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "derive-test" \
+ --actor user_1 \
+ --scopes "read,write" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"derive-test","actor_id":"user_1","scopes":["read","write"]}')
+
+echo "$ISSUE_RESP" | jq .
+
+API_SECRET=$(echo "$ISSUE_RESP" | jq -r '.secret')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+## Derive a JWT
+
+Send the parent key's secret to the derive endpoint with `TOKEN_ALGORITHM_JWT`:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys derive-token "$API_SECRET" \
+ --algorithm jwt \
+ --ttl 1h \
+ --claims '{"role": "viewer", "tenant": "acme"}' \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
+echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$API_SECRET\",
+ \"algorithm\": \"TOKEN_ALGORITHM_JWT\",
+ \"ttl\": \"1h\",
+ \"scopes\": [\"read\"],
+ \"custom_claims\": {\"role\": \"viewer\", \"tenant\": \"acme\"}
+ }")
+
+echo "$RESPONSE" | jq .
+
+JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
+echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+### Request fields
+
+The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or
+`TOKEN_ALGORITHM_MACAROON`), optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For
+the complete field reference, see the
+[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
+
+### Response
+
+The response contains a `token` object with `token.token` (the derived token string),
+`token.expire_time`, `token.scopes`, and `token.claims`. For the complete field reference, see the
+[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
+
+## Verify a derived token
+
+Derived tokens are verified on the same data plane endpoint as API keys:
+
+
+
+
+
+
+```bash
+talos keys verify "$JWT_TOKEN" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$JWT_TOKEN\"}" | jq .
+```
+
+
+
+
+The verification response includes the token's scopes, actor, and metadata from the parent key.
+
+## Derive a macaroon
+
+Macaroons use HMAC-based authentication with support for caveats:
+
+
+
+
+
+
+```bash
+talos keys derive-token "$API_SECRET" \
+ --algorithm macaroon \
+ --ttl 30m \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$API_SECRET\",
+ \"algorithm\": \"TOKEN_ALGORITHM_MACAROON\",
+ \"ttl\": \"30m\"
+ }" | jq .
+```
+
+
+
+
+## JWT vs macaroon
+
+| Feature | JWT | Macaroon |
+| ------------------------ | -------------------------------------------------- | ----------------------------------------- |
+| Verification | Signature-based (can verify client-side with JWKS) | HMAC-based (requires server verification) |
+| Size | Larger (base64 JSON + signature) | Smaller (binary format) |
+| Client-side verification | Yes, via JWKS endpoint | No |
+| Custom claims | Yes | Yes (as caveats) |
+
+## JWKS endpoint
+
+For client-side JWT verification, fetch the public keys from the JWKS endpoint:
+
+
+
+
+
+
+```bash
+talos jwk get -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
+```
+
+
+
+
+Configure your JWT library to fetch keys from this URL. The keys are loaded from the server's JWKS
+configuration and are typically cached.
+
+## Scope restrictions
+
+Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any
+scope that the parent key does not have, the request fails with a `403 Forbidden` error. To restrict
+scopes, request only scopes that exist on the parent key.
+
+## Next steps
+
+- [Issue and verify](issue-and-verify.md) — create the parent API keys used for derivation
+- [Key lifecycle](key-lifecycle.md) — rotate and revoke parent keys
+- [Self-revocation](self-revocation.md) — allow key holders to revoke their own keys
diff --git a/docs/talos/integrate/error-handling.md b/docs/talos/integrate/error-handling.md
new file mode 100644
index 0000000000..b2196626dc
--- /dev/null
+++ b/docs/talos/integrate/error-handling.md
@@ -0,0 +1,128 @@
+---
+title: Error handling
+description: Error response format, error codes, and retry logic
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Error handling
+
+All Talos API errors follow a consistent JSON format. This guide covers the error response
+structure, common error codes, and retry strategies.
+
+
+
+
+## Error response format
+
+Error responses use this structure:
+
+```json
+{
+ "error": {
+ "code": 400,
+ "status": "Bad Request",
+ "message": "The API key format is invalid.",
+ "reason": "invalid_api_key_format"
+ }
+}
+```
+
+| Field | Description |
+| --------------- | --------------------------------- |
+| `error.code` | HTTP status code |
+| `error.status` | HTTP status text |
+| `error.message` | Human-readable error description |
+| `error.reason` | Machine-readable error identifier |
+
+## Verification errors
+
+The verify endpoint (`POST /v2/admin/apiKeys:verify`) returns errors differently from admin
+endpoints. Instead of an HTTP error, it returns `200 OK` with `is_active: false` and a structured
+error code:
+
+```json
+{
+ "is_active": false,
+ "error_code": "VERIFICATION_ERROR_REVOKED",
+ "error_message": "The API key has been revoked."
+}
+```
+
+For the complete list of verification error codes (`VERIFICATION_ERROR_*`), see the
+[error codes reference](../reference/error-codes.md#verification-error-codes).
+
+## HTTP status codes
+
+For the complete list of HTTP status codes and error IDs, see the
+[error codes reference](../reference/error-codes.md).
+
+Key categories:
+
+- **4xx errors**: Client errors (bad request, not found, conflict). Fix the request before retrying.
+- **5xx errors**: Server errors. Retry with exponential backoff.
+
+## Retry strategy
+
+### Safe to retry
+
+- **503 Service Unavailable** — the server is temporarily overloaded. Retry with exponential
+ backoff.
+- **504 Gateway Timeout** — the request timed out. Retry with backoff.
+- **Network errors** — connection refused, DNS failure, etc. Retry with backoff.
+
+### Not safe to retry (without idempotency key)
+
+- **409 Conflict** — the resource already exists. Check the response and adjust.
+- **400 Bad Request** — fix the request before retrying.
+
+### Idempotency key
+
+When issuing API keys, you can include a `request_id` in the request body. This field is stored with
+the key for client-side deduplication:
+
+
+
+
+
+
+```bash
+# Note: request_id is only available via the HTTP API.
+talos keys issue "my-service" --actor user_1 -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "my-service",
+ "actor_id": "user_1",
+ "request_id": "unique-request-id-123"
+ }' | jq .
+```
+
+
+
+
+The `request_id` is recorded in the key's metadata. The server does not enforce server-side
+idempotent replay (sending the same `request_id` twice creates two keys).
+
+## Recommended backoff
+
+```
+attempt 1: wait 100ms
+attempt 2: wait 200ms
+attempt 3: wait 400ms
+attempt 4: wait 800ms
+attempt 5: wait 1600ms (give up after this)
+```
+
+Add jitter (random 0-50% of the wait time) to avoid thundering herd effects.
+
+## Next steps
+
+- [Issue and verify](issue-and-verify.md) — verification response format
+- [Batch operations](batch-operations.md) — partial failure handling
diff --git a/docs/talos/integrate/import-keys.md b/docs/talos/integrate/import-keys.md
new file mode 100644
index 0000000000..2f9e6c2d9c
--- /dev/null
+++ b/docs/talos/integrate/import-keys.md
@@ -0,0 +1,233 @@
+---
+title: Import existing keys
+description: Import API keys from external systems into Talos
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Import existing keys
+
+Talos can manage API keys that were created outside the system. Import lets you migrate from a
+legacy key management solution or centralize keys from multiple providers without rotating
+credentials. For large migrations, use the batchImport API to import up to 1000 keys in a single
+request.
+
+## How import works
+
+When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original
+key is never stored. Verification works by computing the same hash and looking it up in the
+database.
+
+Imported keys support the same features as issued keys: scopes, metadata, expiration, token
+derivation (JWT/macaroon), and revocation.
+
+
+
+
+## Import a single key
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys imported import "Stripe production key" \
+ --raw-key "sk_live_test_51OxAM2Qly" \
+ --actor payment-service \
+ --scopes "payments:read,payments:write" \
+ --ttl 8760h \
+ --metadata '{"source": "stripe", "environment": "production"}' \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
+echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "raw_key": "sk_live_test_51OxAM2Qly",
+ "name": "Stripe production key",
+ "actor_id": "payment-service",
+ "scopes": ["payments:read", "payments:write"],
+ "ttl": "8760h",
+ "metadata": {"source": "stripe", "environment": "production"}
+ }')
+
+echo "$RESPONSE" | jq .
+
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+### Request fields
+
+The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`,
+`ttl`, and `metadata`. For the complete field reference, see the
+[ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
+
+The response returns an `imported_api_key` object. The `raw_key` is **never returned** after import.
+
+## Verify an imported key
+
+Imported keys use the same verification endpoint as issued keys. The data plane automatically
+detects the credential type:
+
+
+
+
+
+
+```bash
+talos keys verify "sk_live_test_51OxAM2Qly" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d '{"credential":"sk_live_test_51OxAM2Qly"}' | jq .
+```
+
+
+
+
+## Batch import
+
+Import up to 1000 keys in a single request:
+
+
+
+
+
+
+```bash
+talos keys imported batch-import --file - -e "$TALOS_URL" <<'JSON'
+[
+ {"raw_key": "ghp_batch_key_001", "name": "GitHub PAT 1", "actor_id": "dev-team"},
+ {"raw_key": "ghp_batch_key_002", "name": "GitHub PAT 2", "actor_id": "dev-team"}
+]
+JSON
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "requests": [
+ {"raw_key": "ghp_batch_key_001", "name": "GitHub PAT 1", "actor_id": "dev-team"},
+ {"raw_key": "ghp_batch_key_002", "name": "GitHub PAT 2", "actor_id": "dev-team"}
+ ]
+ }' | jq .
+```
+
+
+
+
+### Batch response
+
+The response includes a `results` array with per-item outcomes (`imported_api_key` on success,
+`error_code` and `error_message` on failure), plus `success_count` and `failure_count` counters. If
+at least one key succeeds, the HTTP response is `200 OK`.
+
+For the complete response field reference, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx).
+For batch import error codes, see the
+[error codes reference](../reference/error-codes.md#batch-import-error-codes).
+
+## List imported keys
+
+
+
+
+
+
+```bash
+talos keys imported list -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/importedApiKeys?actor_id=payment-service&page_size=10" | jq .
+```
+
+
+
+
+## Revoke an imported key
+
+Imported keys are revoked through the same unified endpoint as issued keys:
+
+
+
+
+
+
+```bash
+talos keys revoke "$IMPORTED_KEY_ID" --reason superseded -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/$IMPORTED_KEY_ID:revoke" \
+ -H "Content-Type: application/json" \
+ -d '{"reason": "REVOCATION_REASON_SUPERSEDED"}'
+echo ""
+echo "Imported key revoked"
+```
+
+
+
+
+## Delete an imported key
+
+For permanent removal (no audit trail), use the delete endpoint:
+
+
+
+
+
+
+```bash
+talos keys imported delete "$IMPORTED_KEY_ID" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X DELETE "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID"
+echo ""
+echo "Imported key deleted"
+```
+
+
+
+
+:::caution Delete is permanent and irreversible. Prefer revocation for audit trail. :::
+
+## Next steps
+
+- [Batch operations](batch-operations.md) -- batch verify and batch import in detail
+- [Key lifecycle](key-lifecycle.md) -- update, rotate, and revoke keys
+- [Derive tokens](derive-tokens.md) -- mint JWTs or macaroons from imported keys
diff --git a/docs/talos/integrate/index.md b/docs/talos/integrate/index.md
new file mode 100644
index 0000000000..fb94a7e99e
--- /dev/null
+++ b/docs/talos/integrate/index.md
@@ -0,0 +1,49 @@
+---
+title: Integrate
+description: Add API key authentication to your application
+---
+
+# Integrate Ory Talos
+
+Ory Talos exposes two HTTP APIs that map to distinct responsibilities:
+
+- **Admin plane** (`/v2/admin/...`) — Create, update, rotate, and revoke API keys. Deploy behind
+ your internal network or VPN.
+- **Data plane** (`/v2/apiKeys:...`) — Verify credentials at the edge. Designed for sub-millisecond
+ latency with caching enabled.
+
+Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the
+data plane every time a request arrives.
+
+## Common workflows
+
+| Task | Endpoint | Guide |
+| --------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
+| Issue a key and verify it | `POST /v2/admin/issuedApiKeys`, `POST /v2/admin/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
+| Import keys from another system | `POST /v2/admin/importedApiKeys` | [Import keys](import-keys.md) |
+| Mint short-lived JWT or macaroon tokens | `POST /v2/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
+| Verify many credentials at once | `POST /v2/admin/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
+| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
+| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
+| Let key holders revoke their own key | `POST /v2/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
+| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
+
+## Authentication
+
+The admin plane does not enforce authentication by default. Protect it at the infrastructure level
+(VPN, service mesh, reverse proxy with mTLS). The data plane is public-facing and requires no
+authentication — callers supply the credential they want to verify.
+
+## Request format
+
+All endpoints accept and return JSON with `Content-Type: application/json`. Field names use
+`snake_case` (for example `actor_id`, `key_id`, `expire_time`).
+
+Durations accept both Go format (`168h`, `30m`, `1h30m`) and protobuf format (`604800s`).
+
+Timestamps follow RFC 3339 in UTC (`2025-06-15T10:30:00Z`).
+
+## SDK and examples
+
+- [curl cheat sheet](sdk/curl.md) — every endpoint as a copy-paste curl command
+- [Go SDK](sdk/go.md) — using the generated Go client
diff --git a/docs/talos/integrate/ip-restrictions.md b/docs/talos/integrate/ip-restrictions.md
new file mode 100644
index 0000000000..d8c4c70e98
--- /dev/null
+++ b/docs/talos/integrate/ip-restrictions.md
@@ -0,0 +1,253 @@
+---
+title: IP restrictions
+description: Restrict API key usage to specific IP addresses or CIDR ranges
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# IP restrictions
+
+IP restrictions let you limit which client IPs can use an API key. When enabled, verification
+rejects requests from IPs outside the allowed CIDR ranges. Keys without IP restrictions are
+unrestricted.
+
+## Prerequisites
+
+A running Talos server. See the [quickstart](../quickstart/index.md) to start one locally.
+
+
+
+
+## Configure client IP source
+
+By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server
+runs behind a reverse proxy or CDN, configure the correct header in your Talos config:
+
+```yaml
+serve:
+ http:
+ client_ip_source: CLIENT_IP_SOURCE_CF_CONNECTING_IP
+```
+
+Supported values:
+
+- `CLIENT_IP_SOURCE_UNSPECIFIED` or `CLIENT_IP_SOURCE_REMOTE_ADDR` — TCP remote address (default)
+- `CLIENT_IP_SOURCE_CF_CONNECTING_IP` — Cloudflare
+- `CLIENT_IP_SOURCE_X_FORWARDED_FOR` — Standard proxy header
+- `CLIENT_IP_SOURCE_X_REAL_IP` — Nginx
+- `CLIENT_IP_SOURCE_TRUE_CLIENT_IP` — Cloudflare Enterprise
+
+This is a global setting — all IP restriction checks use the same source. Set it once to match your
+infrastructure topology.
+
+## Issue a key with IP restrictions
+
+Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both
+individual IPs (with `/32` or `/128` suffix) and CIDR ranges:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "restricted-key" \
+ --actor service_payments \
+ --allowed-cidrs "127.0.0.1/32,10.0.0.0/8" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "restricted-key",
+ "actor_id": "service_payments",
+ "ip_restriction": {
+ "allowed_cidrs": ["127.0.0.1/32", "10.0.0.0/8"]
+ }
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+For the complete request field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+
+## Verify from an allowed IP
+
+When the client IP is within an allowed CIDR range, verification succeeds:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\": \"$API_SECRET\"}")
+
+echo "$VERIFY_RESPONSE" | jq .
+```
+
+
+
+
+The response includes the key metadata with `is_active: true`.
+
+## Verification from a disallowed IP
+
+When the client IP is outside all allowed CIDR ranges, verification returns
+`VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does not reveal which CIDRs are configured.
+
+For the full list of verification error codes, see the
+[error codes reference](../reference/error-codes.md#verification-error-codes).
+
+## Update IP restrictions on an existing key
+
+Use `PATCH` to add, change, or remove IP restrictions on an existing key:
+
+
+
+
+
+
+```bash
+talos keys issued update "$KEY_ID" \
+ --allowed-cidrs "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16" \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+UPDATE_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "ip_restriction": {
+ "allowed_cidrs": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
+ }
+ }')
+
+echo "$UPDATE_RESPONSE" | jq .
+```
+
+
+
+
+To remove all IP restrictions (making the key unrestricted), set `allowed_cidrs` to an empty array:
+
+
+
+
+
+
+```bash
+talos keys issued update "$KEY_ID" \
+ --allowed-cidrs "" \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+UNRESTRICT_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "ip_restriction": {
+ "allowed_cidrs": []
+ }
+ }')
+
+echo "$UNRESTRICT_RESPONSE" | jq .
+```
+
+
+
+
+For the complete update field reference, see the
+[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+
+## Import keys with IP restrictions
+
+You can also set IP restrictions when importing external keys:
+
+
+
+
+
+
+```bash
+talos keys imported import "imported-restricted" \
+ --raw-key "sk_live_example_key_for_import_test" \
+ --actor "user_restrict" \
+ --allowed-cidrs "203.0.113.0/24" \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+IMPORT_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "imported-restricted",
+ "raw_key": "sk_live_example_key_for_import_test",
+ "actor_id": "user_restrict",
+ "ip_restriction": {
+ "allowed_cidrs": ["203.0.113.0/24"]
+ }
+ }')
+
+echo "$IMPORT_RESPONSE" | jq .
+```
+
+
+
+
+For the complete import field reference, see the
+[ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
+
+## Behavior notes
+
+- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key
+ is unrestricted (all IPs allowed).
+- **Cache TTL**: IP restriction changes take effect after the cache TTL expires. See
+ [cache configuration](../operate/cache/index.md) for TTL settings.
+- **Fail-closed**: If client IP resolution fails, the request is denied.
+- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and
+ `/128` for single IPv6 addresses.
+- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens
+ (JWTs/macaroons). Token verification checks the key's IP restrictions at derivation time.
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.md
new file mode 100644
index 0000000000..81f96491f1
--- /dev/null
+++ b/docs/talos/integrate/issue-and-verify.md
@@ -0,0 +1,214 @@
+---
+title: Issue and verify API keys
+description: Create API keys on the admin plane and verify them on the data plane
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Issue and verify API keys
+
+This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are
+executable and tested in CI.
+
+## Prerequisites
+
+A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start
+one locally.
+
+
+
+
+## Issue an API key
+
+Send a request to the admin plane to create a new key:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "backend-service" \
+ --actor user_42 \
+ --scopes "read:orders,write:orders" \
+ --ttl 720h \
+ --metadata '{"team": "payments", "environment": "staging"}' \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "backend-service",
+ "actor_id": "user_42",
+ "scopes": ["read:orders", "write:orders"],
+ "ttl": "720h",
+ "metadata": {"team": "payments", "environment": "staging"}
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+### Request fields
+
+The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`,
+`ttl`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+
+### Response fields
+
+The response contains two top-level fields:
+
+- **`issued_api_key`** — The key metadata (ID, name, actor, scopes, status, timestamps).
+- **`secret`** — The full API key credential. This value is returned **only once** and cannot be
+ retrieved later. Store it securely.
+
+For the complete metadata field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+
+## Verify a key
+
+Send the secret to the data plane to check whether a credential is valid:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+
+
+
+### Verification response
+
+The response includes `is_active` (boolean), `key_id`, `actor_id`, `scopes`, `metadata`, and
+`expire_time` when valid. When `is_active` is `false`, `error_code` and `error_message` indicate the
+reason. When rate limit enforcement is enabled (Commercial), the response also includes
+`rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the
+complete field reference, see the
+[VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+
+### Verification error codes
+
+When `is_active` is `false`, the `error_code` field indicates why. Common codes include
+`VERIFICATION_ERROR_EXPIRED`, `VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and
+`VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's rate limit quota is exhausted). For
+the complete list, see the
+[verification error codes reference](../reference/error-codes.md#verification-error-codes).
+
+## Cache bypass
+
+Verification results are cached for performance. After revoking a key, you can bypass the cache for
+immediate consistency:
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d '{"credential":"sk_..."}'
+```
+
+Cache control headers:
+
+| Header | Effect |
+| ------------------------- | ------------------------------------------- |
+| `Cache-Control: no-cache` | Bypass cache read, force fresh DB lookup |
+| `Cache-Control: no-store` | Bypass both cache read and write |
+| `Pragma: no-cache` | Same as `no-cache` (HTTP/1.0 compatibility) |
+
+## Retrieve a key by ID
+
+Look up key metadata without the secret:
+
+
+
+
+
+
+```bash
+talos keys issued get "$KEY_ID" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" | jq .
+```
+
+
+
+
+The secret is never returned from `GET` requests.
+
+## List keys
+
+List all issued keys with optional filtering and pagination:
+
+
+
+
+
+
+```bash
+talos keys issued list --actor user_42 --page-size 10 -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
+```
+
+
+
+
+### Query parameters
+
+Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status`
+(filtering). For the complete parameter reference, see the
+[ListIssuedAPIKeys API reference](../reference/api/admin-plane-service-list-issued-api-keys.api.mdx).
+
+The response includes a `next_page_token` field. When empty, you have reached the last page.
+
+## Next steps
+
+- [Key lifecycle](key-lifecycle.md) — update, rotate, and revoke keys
+- [Import keys](import-keys.md) — bring existing keys into Talos
+- [Derive tokens](derive-tokens.md) — mint short-lived JWTs or macaroons
+- [Error handling](error-handling.md) — error response format and retry logic
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.md
new file mode 100644
index 0000000000..0d93dba544
--- /dev/null
+++ b/docs/talos/integrate/key-lifecycle.md
@@ -0,0 +1,236 @@
+---
+title: Key lifecycle
+description: Update, rotate, and revoke API keys
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Key lifecycle
+
+After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All
+lifecycle operations use the admin plane.
+
+
+
+
+First, issue a key to work with:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "lifecycle-test" \
+ --actor user_1 \
+ --scopes "read,write" \
+ --metadata '{"team":"backend"}' \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"lifecycle-test","actor_id":"user_1","scopes":["read","write"],"metadata":{"team":"backend"}}')
+
+echo "$ISSUE_RESP" | jq .
+
+API_SECRET=$(echo "$ISSUE_RESP" | jq -r '.secret')
+KEY_ID=$(echo "$ISSUE_RESP" | jq -r '.key_id')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+## Update key metadata
+
+Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the
+secret:
+
+
+
+
+
+
+```bash
+talos keys issued update "$KEY_ID" \
+ --name "lifecycle-test-updated" \
+ --scopes "read" \
+ --metadata '{"team": "backend", "tier": "premium"}' \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "lifecycle-test-updated",
+ "scopes": ["read"],
+ "metadata": {"team": "backend", "tier": "premium"},
+ "update_mask": {"paths": ["name", "scopes", "metadata"]}
+ }' | jq .
+```
+
+
+
+
+### Update mask
+
+The `update_mask` field controls which fields are modified. Only fields listed in `paths` are
+changed. This follows the [AIP-134](https://google.aip.dev/134) standard for partial updates.
+
+Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete
+field reference, see the
+[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+
+## Rotate a key
+
+Rotation creates a new key with a new secret and immediately revokes the old one:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issued rotate "$KEY_ID" \
+ --scopes "read,write,admin" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+NEW_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+NEW_KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+echo "export API_SECRET=$NEW_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys/${KEY_ID}:rotate" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "scopes": ["read", "write", "admin"],
+ "update_mask": {"paths": ["scopes"]}
+ }')
+
+echo "$RESPONSE" | jq .
+
+NEW_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+NEW_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+echo "export API_SECRET=$NEW_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+### Rotation response
+
+The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once),
+and `old_issued_api_key` (status `KEY_STATUS_REVOKED`). For the complete field reference, see the
+[RotateIssuedAPIKey API reference](../reference/api/admin-plane-service-rotate-issued-api-key.api.mdx).
+
+### Zero-downtime rotation
+
+The `:rotate` endpoint revokes the old key immediately. For zero-downtime rotation:
+
+1. Issue a new key with `POST /v2/admin/issuedApiKeys`
+2. Deploy the new secret to all services
+3. Verify the new secret works everywhere
+4. Revoke the old key with `POST /v2/admin/apiKeys/{old_key_id}:revoke`
+
+## Revoke a key
+
+Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache
+TTL):
+
+
+
+
+
+
+```bash
+talos keys revoke "$KEY_ID" --reason superseded -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+ -H "Content-Type: application/json" \
+ -d '{"reason": "REVOCATION_REASON_SUPERSEDED"}'
+echo ""
+echo "Key revoked"
+```
+
+
+
+
+### Revocation reasons
+
+Standard reasons include `REVOCATION_REASON_KEY_COMPROMISE`, `REVOCATION_REASON_SUPERSEDED`,
+`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only).
+For the complete list, see the
+[RevokeAPIKey API reference](../reference/api/admin-plane-service-revoke-api-key.api.mdx).
+
+When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable
+explanation.
+
+### Revocation and caching
+
+Revocation takes effect in the database immediately. However, if caching is enabled, previously
+cached verification results may remain valid until the cache entry expires. To force immediate
+effect, use the `Cache-Control: no-cache` header on verification requests.
+
+## Verify after revocation
+
+Confirm the key is no longer valid:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" --no-cache -e "$TALOS_URL" || true
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+
+
+
+## Next steps
+
+- [Self-revocation](self-revocation.md) -- let key holders revoke their own keys
+- [Issue and verify](issue-and-verify.md) -- create new keys to replace revoked ones
+- [Error handling](error-handling.md) -- handle revocation-related errors
diff --git a/docs/talos/integrate/rate-limiting.md b/docs/talos/integrate/rate-limiting.md
new file mode 100644
index 0000000000..ed34a38473
--- /dev/null
+++ b/docs/talos/integrate/rate-limiting.md
@@ -0,0 +1,229 @@
+---
+title: Rate limiting
+description: Attach and enforce rate limit policies on API keys
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Rate limiting
+
+Rate limit policies let you cap how many verification requests a key can serve within a time window.
+Talos stores the policy on the key, returns it in verification responses, and -- in the Commercial
+edition -- enforces it server-side. For background on how enforcement works in each edition, see the
+[rate limiting concepts page](../concepts/rate-limiting.md).
+
+## Prerequisites
+
+A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to
+start one locally.
+
+
+
+
+## Attach a rate limit policy
+
+Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a
+`window` (time window as a duration string, e.g. `"60s"`):
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "rate-limited-key" \
+ --actor service_api \
+ --rate-limit-quota 100 \
+ --rate-limit-window "60s" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "rate-limited-key",
+ "actor_id": "service_api",
+ "rate_limit_policy": {
+ "quota": 100,
+ "window": "60s"
+ }
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+The response includes the full key metadata with the `rate_limit_policy` attached. For the complete
+request and response field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+
+## Verify a rate-limited key
+
+Verify the key as you would any other credential. When the key has a rate limit policy, the response
+includes the policy metadata:
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+
+
+
+When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining`
+(approximate requests available before the limit is reached) and `rate_limit_reset_time` (when full
+capacity is recovered). For the complete response field reference, see the
+[VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+
+## Exceeding the limit
+
+When a key's quota is exhausted, verification returns `is_active: false` with error code
+`VERIFICATION_ERROR_RATE_LIMITED` (Commercial edition). The response body includes the error code
+and a human-readable message:
+
+```json
+{
+ "is_active": false,
+ "error_code": "VERIFICATION_ERROR_RATE_LIMITED",
+ "error_message": "Rate limit exceeded"
+}
+```
+
+The HTTP response also includes a `Retry-After` header indicating how many seconds the client should
+wait before retrying. In the OSS edition, enforcement is external -- Talos always returns the policy
+metadata but does not reject requests based on quota.
+
+For the complete list of verification error codes, see the
+[error codes reference](../reference/error-codes.md#verification-error-codes).
+
+## Update rate limit policy
+
+Use `PATCH` to change a key's rate limit policy without rotating the secret. Include
+`rate_limit_policy` in the `update_mask`:
+
+
+
+
+```bash
+talos keys issued update "$KEY_ID" \
+ --rate-limit-quota 500 \
+ --rate-limit-window "120s" \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "rate_limit_policy": {
+ "quota": 500,
+ "window": "120s"
+ },
+ "update_mask": {"paths": ["rate_limit_policy"]}
+ }' | jq .
+```
+
+
+
+
+The updated policy takes effect on the next verification request (subject to cache TTL). For the
+complete update field reference, see the
+[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+
+## Remove rate limit policy
+
+To remove a rate limit policy entirely, set `rate_limit_policy` to an empty object:
+
+
+
+
+```bash
+talos keys issued update "$KEY_ID" \
+ --rate-limit-quota 0 \
+ --rate-limit-window "0s" \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "rate_limit_policy": {},
+ "update_mask": {"paths": ["rate_limit_policy"]}
+ }' | jq .
+```
+
+
+
+
+Once removed, the key is no longer subject to rate limiting.
+
+## HTTP response headers
+
+When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in
+verification responses:
+
+| Header | When present | Description |
+| ------------------ | -------------------- | -------------------------------------------------- |
+| `RateLimit-Policy` | Always (with policy) | Declares the quota and window: `100;w=60` |
+| `RateLimit` | Always (with policy) | Current state: `limit=100, remaining=42, reset=18` |
+| `Retry-After` | Only when limited | Seconds to wait before the next allowed request |
+
+These headers are present in both editions. In the OSS edition, your API gateway can read them to
+apply enforcement. In the Commercial edition, clients can use them for backoff and retry logic.
+
+## Behavior notes
+
+- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is
+ down), verification succeeds but rate limit metadata is omitted. Limiter failures never block
+ legitimate traffic.
+- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result
+ is served from cache, the rate limiter is not consulted. This means cached responses do not
+ decrement the counter.
+- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets,
+ even if they belong to the same actor.
+- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate
+ effect, use the `Cache-Control: no-cache` header on verification requests.
+
+## Next steps
+
+- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs.
+ Commercial
+- [Key lifecycle](./key-lifecycle.md) -- update, rotate, and revoke keys
+- [Error handling](./error-handling.md) -- error response format and retry logic
diff --git a/docs/talos/integrate/sdk/curl.md b/docs/talos/integrate/sdk/curl.md
new file mode 100644
index 0000000000..e6a7c53239
--- /dev/null
+++ b/docs/talos/integrate/sdk/curl.md
@@ -0,0 +1,270 @@
+---
+title: curl cheat sheet
+description: Every Talos API endpoint as a copy-paste curl command
+---
+
+# curl cheat sheet
+
+Replace `$TALOS_URL` with your Talos server address (e.g., `http://127.0.0.1:4420`).
+
+
+
+
+## Admin plane — Issued keys
+
+### Issue a key
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "my-service",
+ "actor_id": "user_123",
+ "scopes": ["read", "write"],
+ "ttl": "720h",
+ "metadata": {"team": "backend"}
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+### Get a key
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" | jq .
+```
+
+### List keys
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=50&actor_id=user_123&status=KEY_STATUS_ACTIVE" | jq .
+```
+
+### Update a key
+
+
+
+```bash
+curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "updated-name",
+ "scopes": ["read"],
+ "update_mask": {"paths": ["name", "scopes"]}
+ }' | jq .
+```
+
+### Rotate a key
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys/${KEY_ID}:rotate" \
+ -H "Content-Type: application/json" \
+ -d '{}')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+## Admin plane — Imported keys
+
+### Import a key
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "raw_key": "sk_live_abc123",
+ "name": "External key",
+ "actor_id": "user_123",
+ "scopes": ["read"]
+ }')
+
+echo "$RESPONSE" | jq .
+
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+### Batch import
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "requests": [
+ {"raw_key": "key_1", "name": "Key 1", "actor_id": "user_1"},
+ {"raw_key": "key_2", "name": "Key 2", "actor_id": "user_2"}
+ ]
+ }' | jq .
+```
+
+### Get an imported key
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
+```
+
+### List imported keys
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/importedApiKeys?page_size=50&actor_id=user_123" | jq .
+```
+
+### Delete an imported key
+
+
+
+```bash
+curl -s -X DELETE "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
+```
+
+## Admin plane — Token derivation
+
+### Derive a JWT token
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$API_SECRET\",
+ \"algorithm\": \"TOKEN_ALGORITHM_JWT\",
+ \"ttl\": \"1h\",
+ \"scopes\": [\"read\"],
+ \"custom_claims\": {\"role\": \"viewer\"}
+ }")
+
+echo "$RESPONSE" | jq .
+
+JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
+echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+```
+
+### Derive a macaroon token
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$API_SECRET\",
+ \"algorithm\": \"TOKEN_ALGORITHM_MACAROON\",
+ \"ttl\": \"30m\"
+ }" | jq .
+```
+
+### Get JWKS (public keys)
+
+
+
+```bash
+curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
+```
+
+## Data plane
+
+### Verify a credential
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+### Verify with cache bypass
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+### Batch verify
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"requests\": [
+ {\"credential\": \"$API_SECRET\"},
+ {\"credential\": \"$JWT_TOKEN\"}
+ ]
+ }" | jq .
+```
+
+## Revocation
+
+### Revoke a key (admin)
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+ -H "Content-Type: application/json" \
+ -d '{"reason": "REVOCATION_REASON_KEY_COMPROMISE"}' | jq .
+```
+
+### Self-revoke a key
+
+
+
+```bash
+# Issue a fresh key for the self-revocation demo
+SELF_REVOKE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"self-revoke-demo","actor_id":"user_123"}')
+
+SELF_REVOKE_SECRET=$(echo "$SELF_REVOKE_RESP" | jq -r '.secret')
+
+curl -s -X POST "$TALOS_URL/v2/apiKeys:selfRevoke" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$SELF_REVOKE_SECRET\",
+ \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"
+ }" | jq .
+```
+
+## Health checks
+
+
+
+```bash
+# Liveness
+curl -s "$TALOS_URL/health/alive" | jq .
+
+# Readiness
+curl -s "$TALOS_URL/health/ready" | jq .
+```
diff --git a/docs/talos/integrate/sdk/go.md b/docs/talos/integrate/sdk/go.md
new file mode 100644
index 0000000000..cfa25ae689
--- /dev/null
+++ b/docs/talos/integrate/sdk/go.md
@@ -0,0 +1,192 @@
+---
+title: Go SDK
+description: Using the generated Go HTTP client
+---
+
+# Go SDK
+
+Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is
+generated using `openapi-generator` and lives in the `internal/client/generated` package.
+
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by
+external Go modules. It is used for Talos's own integration tests and the admin UI backend. If you
+need a Go client for your application, generate one from the OpenAPI spec at
+`api/talos.openapi-v2.json` using [OpenAPI Generator](https://openapi-generator.tech/). :::
+
+
+
+
+## Generate your own client
+
+```bash
+openapi-generator generate \
+ -i api/talos.openapi-v2.json \
+ -g go \
+ -o generated/go-client
+```
+
+The examples below use the internal client's types for illustration. A generated external client has
+the same API shape.
+
+:::tip Full working example See
+[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go)
+for a complete, runnable program that exercises all operations shown below. :::
+
+
+
+```bash
+go build -o .bin/doctest-go-sdk ./tools/doctest/examples/go_sdk
+./.bin/doctest-go-sdk
+```
+
+## Initialize the client
+
+
+
+```go
+cfg := client.NewConfiguration()
+cfg.Servers = client.ServerConfigurations{
+ {URL: talosURL},
+}
+c := client.NewAPIClient(cfg)
+```
+
+## Issue an API key
+
+
+
+```go
+issueResp, _, err := c.StaticCredentialsAPI.
+ AdminIssueAPIKey(ctx).
+ V2IssueAPIKeyRequest(client.V2IssueAPIKeyRequest{
+ Name: new("my-service"),
+ ActorId: new("user_123"),
+ Scopes: []string{"read", "write"},
+ Ttl: new("720h"),
+ }).
+ Execute()
+if err != nil {
+ return fmt.Errorf("issue key: %w", err)
+}
+
+// Secret is only available at creation time
+issuedKey := issueResp.GetIssuedApiKey()
+fmt.Println("Key ID:", issuedKey.GetKeyId())
+fmt.Println("Secret:", issueResp.GetSecret())
+```
+
+## Verify a credential
+
+
+
+```go
+verifyResp, _, err := c.StaticCredentialsAPI.
+ AdminVerifyAPIKey(ctx).
+ V2VerifyAPIKeyRequest(client.V2VerifyAPIKeyRequest{
+ Credential: new(secret),
+ }).
+ Execute()
+if err != nil {
+ return fmt.Errorf("verify key: %w", err)
+}
+
+if verifyResp.GetIsActive() {
+ fmt.Println("Key is valid, owner:", verifyResp.GetActorId())
+} else {
+ fmt.Println("Key is invalid:", verifyResp.GetErrorMessage())
+}
+```
+
+## Batch verify
+
+
+
+```go
+batchResp, _, err := c.StaticCredentialsAPI.
+ AdminBatchVerifyAPIKeys(ctx).
+ V2BatchVerifyAPIKeysRequest(client.V2BatchVerifyAPIKeysRequest{
+ Requests: []client.V2VerifyAPIKeyRequest{
+ {Credential: new(secret)},
+ {Credential: new("invalid-key-for-testing")},
+ },
+ }).
+ Execute()
+if err != nil {
+ return fmt.Errorf("batch verify: %w", err)
+}
+
+for i, result := range batchResp.GetResults() {
+ fmt.Printf("Key %d: is_active=%v\n", i, result.GetIsActive())
+}
+```
+
+## Revoke a key
+
+Enum fields use typed constants, not raw strings:
+
+
+
+```go
+reason := client.V2REVOCATIONREASON_REVOCATION_REASON_KEY_COMPROMISE
+_, _, err = c.StaticCredentialsAPI.
+ AdminRevokeAPIKey(ctx, keyID).
+ StaticCredentialsAdminRevokeAPIKeyBody(client.StaticCredentialsAdminRevokeAPIKeyBody{
+ Reason: &reason,
+ }).
+ Execute()
+if err != nil {
+ return fmt.Errorf("revoke key: %w", err)
+}
+fmt.Println("Key revoked successfully")
+```
+
+## Derive a JWT token
+
+
+
+```go
+algorithm := client.V2TOKENALGORITHM_TOKEN_ALGORITHM_JWT
+deriveResp, _, err := c.StaticCredentialsAPI.
+ AdminDeriveToken(ctx).
+ V2DeriveTokenRequest(client.V2DeriveTokenRequest{
+ Credential: new(secret),
+ Algorithm: &algorithm,
+ Ttl: new("1h"),
+ Scopes: []string{"read"},
+ }).
+ Execute()
+if err != nil {
+ return fmt.Errorf("derive token: %w", err)
+}
+
+derivedToken := deriveResp.GetToken()
+fmt.Println("JWT:", derivedToken.GetToken())
+```
+
+## Error handling
+
+The SDK returns errors for non-2xx responses. Use the HTTP response to inspect error details:
+
+
+
+```go
+_, httpResp, err := c.StaticCredentialsAPI.
+ AdminGetIssuedAPIKey(ctx, "nonexistent-id").
+ Execute()
+if err != nil {
+ if httpResp != nil {
+ fmt.Println("HTTP status:", httpResp.StatusCode)
+ }
+}
+```
+
+## Regenerating the client
+
+The Go SDK is regenerated with:
+
+```bash
+make generate-sdk
+```
+
+This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to
+`internal/client/generated/`.
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.md
new file mode 100644
index 0000000000..da97d91524
--- /dev/null
+++ b/docs/talos/integrate/self-revocation.md
@@ -0,0 +1,152 @@
+---
+title: Self-revocation
+description: Allow API key holders to revoke their own keys
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Self-revocation
+
+The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the
+secret. This is a data plane operation — it does not require admin access.
+
+## Prerequisites
+
+A running Talos server. See the [quickstart](../quickstart/index.md) to start one locally.
+
+
+
+
+## When to use self-revocation
+
+- **Key compromise** — a user discovers their key was leaked and wants to revoke it immediately.
+- **User-initiated cleanup** — a user decommissions an integration and revokes unused keys.
+- **Security automation** — an automated system detects anomalous usage and revokes the key.
+
+## Self-revoke a key
+
+First, issue a key to get a secret:
+
+
+
+
+
+
+```bash
+SELF_REVOKE_SECRET=$(talos keys issue "self-revoke-demo" \
+ --actor user_99 \
+ --scopes "read:data" \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
+echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+ISSUE_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "self-revoke-demo",
+ "actor_id": "user_99",
+ "scopes": ["read:data"]
+ }')
+
+SELF_REVOKE_SECRET=$(echo "$ISSUE_RESPONSE" | jq -r '.secret')
+echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+Send the full key secret as proof of possession:
+
+
+
+
+
+
+```bash
+talos keys self-revoke "$SELF_REVOKE_SECRET" \
+ --reason key_compromise \
+ -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/apiKeys:selfRevoke" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$SELF_REVOKE_SECRET\",
+ \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"
+ }"
+echo ""
+echo "Key self-revoked"
+```
+
+
+
+
+Verify the key is no longer active:
+
+
+
+
+
+
+```bash
+talos keys verify "$SELF_REVOKE_SECRET" --no-cache -e "$TALOS_URL" || true
+echo "Self-revocation confirmed"
+```
+
+
+
+
+```bash
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d "{\"credential\":\"$SELF_REVOKE_SECRET\"}")
+
+echo "$VERIFY_RESPONSE" | jq .
+
+if echo "$VERIFY_RESPONSE" | jq -e '.is_active == false' > /dev/null 2>&1; then
+ echo "Self-revocation confirmed"
+else
+ echo "ERROR: Key should have been revoked"
+ exit 1
+fi
+```
+
+
+
+
+The request requires `credential` (the full API key secret) and optionally `reason` (revocation
+reason enum). For the complete field reference, see the
+[SelfRevokeAPIKey API reference](../reference/api/data-plane-service-self-revoke-api-key.api.mdx).
+
+Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are
+stateless and cannot be revoked. All revocation reasons except
+`REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
+revocations.
+
+A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is
+immediately revoked.
+
+## Admin vs self-revocation
+
+| | Admin revocation | Self-revocation |
+| --------------------- | ---------------------------------------- | -------------------------------- |
+| Endpoint | `POST /v2/admin/apiKeys/{key_id}:revoke` | `POST /v2/apiKeys:selfRevoke` |
+| Plane | Admin | Data |
+| Authentication | Requires admin access | Proof of possession (key secret) |
+| Identifier | Key ID | Key secret |
+| `PRIVILEGE_WITHDRAWN` | Allowed | Not allowed |
+
+## Next steps
+
+- [Key lifecycle](key-lifecycle.md) — admin-side key management
+- [Error handling](error-handling.md) — handle revocation errors
diff --git a/docs/talos/operate/benchmarks.md b/docs/talos/operate/benchmarks.md
new file mode 100644
index 0000000000..68470f42e7
--- /dev/null
+++ b/docs/talos/operate/benchmarks.md
@@ -0,0 +1,136 @@
+---
+title: Benchmarks
+description: Performance benchmarks and load testing for Ory Talos
+---
+
+# Benchmarks
+
+Talos includes a k6-based load test suite that measures throughput, latency, and correctness under
+concurrent load. Use these benchmarks to validate your deployment and catch performance regressions.
+
+:::note
+
+These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS
+edition uses SQLite, which does not support concurrent writers and cannot handle the parallel load
+generated by multi-VU test profiles.
+
+:::
+
+## Reference results
+
+Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress
+profile (ramping 0→437 VUs over 5 minutes):
+
+| Metric | Value |
+| ------------------- | ------------ |
+| Total requests | ~5,000,000 |
+| Peak throughput | 16,766 req/s |
+| Overall p99 latency | 123ms |
+| Verify p95 latency | 48ms |
+| Verify p99 latency | 95ms |
+| Error rate | 0.00% |
+| Peak VUs | 437 |
+| Key creations | 493/s |
+| Verifications | 3,797/s |
+| Token derivations | 3,797/s |
+
+## Profiles
+
+The test suite provides three profiles selected via the `TEST_PROFILE` environment variable:
+
+| Profile | VUs | Duration | Executor | Purpose |
+| -------- | ----------------- | -------- | ------------ | ---------------------------------------------- |
+| `smoke` | 1 read + 1 write | 15s | constant-vus | Quick validation after changes |
+| `load` | 15 read + 5 write | 2min | constant-vus | Sustained load for regression detection |
+| `stress` | 0→437 ramping | 5min | ramping-vus | Find breaking points and measure peak capacity |
+
+The stress profile ramps through four stages:
+
+1. **Warm-up**: 0→25 VUs over 30s
+2. **Ramp 1**: 25→75 VUs over 60s
+3. **Ramp 2**: 75→150 VUs over 60s
+4. **Hold**: 150 VUs for 120s
+5. **Ramp down**: 150→0 VUs over 30s
+
+Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write
+scenarios (create, rotate, revoke, import, update, self-revoke) get ~30%.
+
+## Running benchmarks
+
+### Prerequisites
+
+- [k6](https://k6.io/docs/get-started/installation/) load testing tool
+- Docker (for local PostgreSQL) or an existing PostgreSQL instance
+- Go toolchain (to build the binary)
+
+### Quick start
+
+```bash
+# Smoke test (quick validation)
+TEST_PROFILE=smoke bash test/load/run.sh
+
+# Load test (sustained)
+TEST_PROFILE=load bash test/load/run.sh
+
+# Stress test (peak capacity)
+TEST_PROFILE=stress bash test/load/run.sh
+```
+
+The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker,
+runs migrations, seeds tenant data, starts the server, and executes k6.
+
+### Using an existing database
+
+```bash
+SKIP_DOCKER=true DB_DSN="postgres://user:pass@host:5432/db?sslmode=disable" \
+ TEST_PROFILE=load bash test/load/run.sh
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+| -------------- | ------------------------------------------------------------------ | ---------------------------------------------- |
+| `TEST_PROFILE` | `smoke` | Test profile: `smoke`, `load`, or `stress` |
+| `BASE_URL` | `http://localhost:4420` | Server base URL |
+| `AUTH_TOKEN` | `test-token` | Bearer token for admin endpoints |
+| `DB_DSN` | `postgres://talos:talos@localhost:5432/talos_test?sslmode=disable` | PostgreSQL connection string |
+| `SKIP_DOCKER` | `false` | Skip Docker PostgreSQL setup (use existing DB) |
+
+## Thresholds
+
+Each profile enforces regression thresholds. Tests fail if any threshold is breached.
+
+### Smoke and load profiles
+
+| Metric | Threshold | Rationale |
+| ----------- | --------- | --------------------------------------- |
+| All checks | 100% pass | Zero tolerance for correctness failures |
+| HTTP errors | 0% | No errors allowed at low concurrency |
+| Overall p99 | < 500ms | Generous headroom for CI runners |
+| Verify p95 | < 50ms | ~25ms measured in CI (postgres) |
+| Verify p99 | < 100ms | Allows for CI variance |
+
+### Stress profile
+
+| Metric | Threshold | Rationale |
+| ----------- | --------- | ------------------------------------- |
+| All checks | 100% pass | Correctness under load |
+| HTTP errors | < 1% | Small tolerance for stress conditions |
+| Overall p99 | < 400ms | ~3x headroom over measured 123ms |
+| Verify p95 | < 100ms | ~2x headroom over measured 48ms |
+| Verify p99 | < 200ms | ~2x headroom over measured 95ms |
+
+## Interpreting results
+
+After a k6 run, look for:
+
+- **`checks` rate**: Must be 100%. Any failure indicates a correctness bug.
+- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases
+ suggest a regression.
+- **`http_req_failed` rate**: Should be 0% for smoke/load. Under 1% for stress.
+- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against
+ the reference results to detect throughput regressions.
+- **`iteration_duration`**: End-to-end time for each VU iteration including all operations.
+
+Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json`
+(machine-readable).
diff --git a/docs/talos/operate/cache/index.md b/docs/talos/operate/cache/index.md
new file mode 100644
index 0000000000..e5037c98be
--- /dev/null
+++ b/docs/talos/operate/cache/index.md
@@ -0,0 +1,31 @@
+---
+title: Cache
+---
+
+# Cache
+
+Talos can cache verification results to reduce database load and improve latency.
+
+## Backends
+
+| Backend | Edition | Shared | Description |
+| ------------------- | ---------- | ------ | ----------------------------- |
+| `noop` | OSS | N/A | No caching (default) |
+| [Memory](memory.md) | Commercial | No | Per-process LRU cache |
+| [Redis](redis.md) | Commercial | Yes | Shared cache across instances |
+
+## Configuration
+
+```yaml
+cache:
+ type: "memory" # "noop", "memory", or "redis"
+ ttl: "5m" # Cache entry lifetime
+```
+
+## Consistency
+
+Caching introduces eventual consistency. A revoked key may continue to pass verification until the
+cache entry expires (default: 5 minutes).
+
+**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for
+individual requests when immediate consistency is required.
diff --git a/docs/talos/operate/cache/memory.md b/docs/talos/operate/cache/memory.md
new file mode 100644
index 0000000000..2f08db13e9
--- /dev/null
+++ b/docs/talos/operate/cache/memory.md
@@ -0,0 +1,35 @@
+---
+title: In-memory cache
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# In-memory cache
+
+The in-memory cache stores verification results in the Talos process using a ristretto-based LRU
+cache.
+
+## Configuration
+
+```yaml
+cache:
+ type: "memory"
+ ttl: "5m"
+ memory:
+ max_size: 104857600 # 100MB
+ num_counters: 10000 # Frequency estimation counters
+```
+
+## Characteristics
+
+- **Per-process**: Each Talos instance has its own cache. Not shared across instances.
+- **LRU eviction**: Least-recently-used entries are evicted when the cache reaches `max_size`.
+- **TTL-based expiry**: Entries expire after the configured `ttl`.
+- **Zero network overhead**: No external dependencies.
+
+## When to use
+
+Use the in-memory cache for single-node deployments or when each Talos instance handles enough
+traffic to benefit from local caching. For multi-instance deployments, consider [Redis](redis.md)
+for shared cache across all instances.
diff --git a/docs/talos/operate/cache/redis.md b/docs/talos/operate/cache/redis.md
new file mode 100644
index 0000000000..9e9064d7b2
--- /dev/null
+++ b/docs/talos/operate/cache/redis.md
@@ -0,0 +1,40 @@
+---
+title: Redis cache
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# Redis cache
+
+Redis provides a shared cache across all Talos instances.
+
+## Configuration
+
+```yaml
+cache:
+ type: "redis"
+ ttl: "5m"
+ redis:
+ addrs: ["redis:6379"]
+ password: "secret"
+ db: 0
+ pool_size: 100
+ timeout: "3s"
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+| ----------- | -------------------- | --------------------- |
+| `addrs` | `["localhost:6379"]` | Redis addresses |
+| `password` | — | Redis password |
+| `db` | `0` | Redis database number |
+| `pool_size` | `100` | Connection pool size |
+| `timeout` | `3s` | Operation timeout |
+
+## When to use
+
+Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances,
+reducing database load. Redis is also required for [edge proxy](../deploy/edge-proxy.md) deployments
+where each edge node shares a regional Redis instance.
diff --git a/docs/talos/operate/configure.md b/docs/talos/operate/configure.md
new file mode 100644
index 0000000000..4bad1b1897
--- /dev/null
+++ b/docs/talos/operate/configure.md
@@ -0,0 +1,112 @@
+---
+title: Configure
+description: Configuration reference for Ory Talos
+---
+
+# Configure
+
+Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set
+through environment variables or CLI flags. See the
+[Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
+environment variable mappings, and precedence rules.
+
+## Hot-reload
+
+Talos watches the config file for changes. Some settings reload automatically, others require a
+restart.
+
+**Hot-reloadable:**
+
+- `credentials.api_keys.default_ttl` / `max_ttl`
+- `credentials.api_keys.prefix.current` / `retired`
+- `credentials.derived_tokens.default_ttl`
+- `credentials.derived_tokens.macaroon.prefix.current` / `retired`
+- `rate_limit.enabled`
+
+**Requires restart** (marked with `x-immutable` in the schema):
+
+- `serve.http.host` / `port`
+- `serve.metrics.host` / `port`
+- `db.dsn`
+- `cache.type` and all cache settings
+- `rate_limit.backend`
+- `log.level` / `format`
+- `tracing.*`
+
+## Minimal configuration
+
+```yaml
+credentials:
+ issuer: "https://api.example.com"
+secrets:
+ default:
+ current: "a-32-byte-or-longer-secret-here!"
+db:
+ dsn: "sqlite:///var/lib/talos/data.db"
+```
+
+## Production configuration
+
+```yaml
+serve:
+ http:
+ host: "0.0.0.0"
+ port: 4420
+ cors:
+ enabled: true
+ allowed_origins: ["https://app.example.com"]
+ request_log:
+ exclude_health_endpoints: true
+ metrics:
+ host: "0.0.0.0"
+ port: 4422
+
+credentials:
+ issuer: "https://api.example.com"
+ api_keys:
+ default_ttl: "2160h" # 90 days
+ max_ttl: "8760h" # 1 year
+ prefix:
+ current: "talos"
+ derived_tokens:
+ jwt:
+ algorithm: "EdDSA"
+ default_ttl: "1h"
+ signing_keys:
+ urls:
+ - "file:///etc/talos/jwks.json"
+
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?max_conns=25&max_conn_lifetime=5m"
+
+cache:
+ type: "redis" # Commercial only
+ ttl: "5m"
+ redis:
+ addrs: ["redis:6379"]
+ password: "secret"
+ pool_size: 100
+ timeout: "3s"
+
+rate_limit: # Commercial only
+ enabled: true
+ backend: redis # "memory" for single-pod, "redis" for multi-pod
+
+secrets:
+ default:
+ current: "a-32-byte-or-longer-secret-here!"
+
+log:
+ level: "info"
+ format: "json"
+
+tracing:
+ enabled: true
+ service_name: "talos"
+ exporter: "otlp"
+ endpoint: "jaeger:4317"
+ sample_rate: 0.01
+```
+
+See the [Configuration reference](../reference/config.md) for all available keys with types,
+defaults, and environment variable mappings.
diff --git a/docs/talos/operate/database/cockroachdb.md b/docs/talos/operate/database/cockroachdb.md
new file mode 100644
index 0000000000..cf38a55d61
--- /dev/null
+++ b/docs/talos/operate/database/cockroachdb.md
@@ -0,0 +1,102 @@
+---
+title: CockroachDB
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# CockroachDB
+
+CockroachDB provides distributed SQL with automatic sharding and multi-region replication.
+
+## Supported versions
+
+CockroachDB 23.1 and later.
+
+## Configuration
+
+```yaml
+db:
+ dsn: "cockroach://talos@crdb:26257/talos?sslmode=verify-full&max_conns=50"
+```
+
+Or via environment variable:
+
+```bash
+export TALOS_DB_DSN="cockroach://talos@crdb:26257/talos?sslmode=verify-full&max_conns=50"
+```
+
+## DSN format
+
+```
+cockroach://user:password@host:port/dbname?param=value¶m=value
+```
+
+Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted
+to `postgres://` since CockroachDB uses the PostgreSQL wire protocol.
+
+## DSN parameters, connection pooling, and TLS
+
+CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including
+both standard and advanced pool modes. For the full parameter reference, see the
+[PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
+[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl)
+documentation.
+
+Key differences from PostgreSQL:
+
+- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of
+ `25`.
+- **No connection limit pressure** — Each CockroachDB node independently manages connections, so
+ total pool sizes can be larger without needing a connection pooler like PgBouncer.
+
+## Migrations
+
+```bash
+talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
+```
+
+## Multi-region
+
+Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification
+latency. Talos does not require special configuration beyond pointing `db.dsn` at the local
+CockroachDB node.
+
+```yaml
+# Region: us-east-1
+db:
+ dsn: "cockroach://talos@crdb-us-east:26257/talos?sslmode=verify-full&max_conns=50"
+
+# Region: eu-west-1
+db:
+ dsn: "cockroach://talos@crdb-eu-west:26257/talos?sslmode=verify-full&max_conns=50"
+```
+
+## Performance
+
+CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For
+verification-heavy workloads:
+
+- Enable [caching](../cache/index.md) to absorb verification reads
+- Use `max_conns=50` or higher — CockroachDB connections are lighter than PostgreSQL
+- Place Talos data plane nodes in the same region as CockroachDB nodes
+
+## Example DSNs
+
+**Development (CockroachDB Serverless):**
+
+```
+cockroach://talos:secret@free-tier.cockroachlabs.cloud:26257/talos?sslmode=require
+```
+
+**Production with standard pooling:**
+
+```
+cockroach://talos@crdb:26257/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt&max_conns=50&max_idle_conns=10&max_conn_lifetime=5m&max_conn_idle_time=1m
+```
+
+**Production with advanced pooling (multi-region):**
+
+```
+cockroach://talos@crdb-local:26257/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt&pool_mode=advanced
+```
diff --git a/docs/talos/operate/database/index.md b/docs/talos/operate/database/index.md
new file mode 100644
index 0000000000..163f881cc3
--- /dev/null
+++ b/docs/talos/operate/database/index.md
@@ -0,0 +1,30 @@
+---
+title: Database
+---
+
+# Database
+
+Talos stores API key data in a relational database. The backend is determined by the DSN scheme in
+`db.dsn`.
+
+## Supported backends
+
+| Backend | Edition | DSN scheme | Use case |
+| ----------------------------- | ---------- | -------------- | ------------------------------------ |
+| [SQLite](sqlite.md) | OSS | `sqlite://` | Development, single-node |
+| [PostgreSQL](postgresql.md) | Commercial | `postgres://` | Recommended production |
+| [MySQL](mysql.md) | Commercial | `mysql://` | Production with MySQL infrastructure |
+| [CockroachDB](cockroachdb.md) | Commercial | `cockroach://` | Multi-region, distributed |
+
+## Configuration
+
+```yaml
+db:
+ dsn: "sqlite:///var/lib/talos/data.db"
+```
+
+The `db.dsn` setting requires a server restart to take effect.
+
+## Migrations
+
+Run `talos migrate up` before first use and after each upgrade. See [Migrations](migrations.md).
diff --git a/docs/talos/operate/database/migrations.md b/docs/talos/operate/database/migrations.md
new file mode 100644
index 0000000000..7a00bd9624
--- /dev/null
+++ b/docs/talos/operate/database/migrations.md
@@ -0,0 +1,69 @@
+---
+title: Migrations
+---
+
+# Migrations
+
+Talos includes built-in database migrations. Run them before first use and after each upgrade.
+
+## Commands
+
+```bash
+# Apply all pending migrations
+talos migrate up --database "sqlite:///var/lib/talos/data.db"
+
+# Roll back the last migration
+talos migrate down --database "sqlite:///var/lib/talos/data.db"
+
+# Check migration status
+talos migrate status --database "sqlite:///var/lib/talos/data.db"
+```
+
+## Upgrade workflow
+
+1. Back up your database
+2. Stop the Talos server
+3. Run `talos migrate up`
+4. Verify with `talos migrate status`
+5. Start the new server binary
+
+## DSN examples
+
+```bash
+# SQLite (OSS)
+talos migrate up --database "sqlite:///var/lib/talos/data.db"
+
+# PostgreSQL (Commercial)
+talos-commercial migrate up --database "postgres://talos:secret@db:5432/talos"
+
+# MySQL (Commercial)
+talos-commercial migrate up --database "mysql://talos:secret@tcp(db:3306)/talos?parseTime=true"
+
+# CockroachDB (Commercial)
+talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
+```
+
+## Kubernetes
+
+Use an init container or Job:
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+ name: talos-migrate
+spec:
+ template:
+ spec:
+ containers:
+ - name: migrate
+ image: oryd/talos:latest
+ command: ["talos", "migrate", "up"]
+ env:
+ - name: TALOS_DB_DSN
+ valueFrom:
+ secretKeyRef:
+ name: talos-secrets
+ key: dsn
+ restartPolicy: OnFailure
+```
diff --git a/docs/talos/operate/database/mysql.md b/docs/talos/operate/database/mysql.md
new file mode 100644
index 0000000000..9609924622
--- /dev/null
+++ b/docs/talos/operate/database/mysql.md
@@ -0,0 +1,153 @@
+---
+title: MySQL
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# MySQL
+
+MySQL is supported as a production database in the Commercial edition.
+
+## Supported versions
+
+MySQL 8.0 and later.
+
+## Configuration
+
+```yaml
+db:
+ dsn: "mysql://talos:secret@tcp(db:3306)/talos?tls=true&parseTime=true"
+```
+
+Or via environment variable:
+
+```bash
+export TALOS_DB_DSN="mysql://talos:secret@tcp(db:3306)/talos?tls=true&parseTime=true"
+```
+
+## DSN format
+
+```
+mysql://user:password@tcp(host:port)/dbname?param=value¶m=value
+```
+
+The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before
+passing the DSN to the Go MySQL driver.
+
+:::caution Required parameter Always include `parseTime=true` in the DSN. Without it, datetime
+columns are returned as byte arrays instead of `time.Time`, causing runtime errors. :::
+
+## DSN parameters
+
+### Connection pool parameters
+
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
+database driver.
+
+| Parameter | Type | Default | Description |
+| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
+| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
+| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
+| `max_conn_lifetime` | duration | `0` (unlimited) | Maximum age of a connection before it is closed and replaced |
+| `max_conn_idle_time` | duration | `0` (unlimited) | Maximum time a connection can sit idle before it is closed |
+
+Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
+
+MySQL uses standard `database/sql` pooling only. There is no advanced pool mode.
+
+### MySQL driver parameters
+
+These parameters are passed through to the underlying Go MySQL driver.
+
+| Parameter | Description | Required |
+| ----------------- | ------------------------------------------ | -------------------------------- |
+| `parseTime` | Parse `DATETIME` columns to `time.Time` | **Yes** — always set to `true` |
+| `tls` | TLS mode (`true`, `skip-verify`, `custom`) | Recommended for production |
+| `charset` | Character set | Defaults to `utf8mb4` |
+| `collation` | Collation | Defaults to `utf8mb4_general_ci` |
+| `loc` | Timezone for time.Time values | Defaults to `UTC` |
+| `timeout` | Connection timeout (e.g., `10s`) | — |
+| `readTimeout` | Read timeout (e.g., `30s`) | — |
+| `writeTimeout` | Write timeout (e.g., `30s`) | — |
+| `multiStatements` | Allow multiple statements per query | Do not enable |
+
+## Connection pooling
+
+MySQL uses Go's `database/sql` connection pool with the `go-sql-driver/mysql` driver.
+
+```yaml
+db:
+ dsn: "mysql://talos:secret@tcp(db:3306)/talos?parseTime=true&max_conns=25&max_idle_conns=5&max_conn_lifetime=5m&max_conn_idle_time=1m"
+```
+
+Pool behavior:
+
+- Connections are created on demand up to `max_conns`
+- Idle connections are kept up to `max_idle_conns`
+- Connections older than `max_conn_lifetime` are closed and replaced
+- Connections idle longer than `max_conn_idle_time` are closed
+
+### Pool sizing
+
+Start with 25 connections per instance. The total pool across all instances should stay below
+MySQL's `max_connections` (default: 151).
+
+| Deployment | `max_conns` | Notes |
+| --------------- | -------------- | ------------------------------------------- |
+| Single instance | `25` | Good starting point |
+| 3 instances | `25` each | 75 total — within default `max_connections` |
+| 5+ instances | `15`–`20` each | Use ProxySQL or MySQL Router to multiplex |
+
+For large deployments, place [ProxySQL](https://proxysql.com/) or
+[MySQL Router](https://dev.mysql.com/doc/mysql-router/en/) between Talos and MySQL for connection
+multiplexing.
+
+## Database preparation
+
+```sql
+CREATE DATABASE talos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'talos'@'%' IDENTIFIED BY 'secret';
+GRANT ALL PRIVILEGES ON talos.* TO 'talos'@'%';
+```
+
+## Migrations
+
+```bash
+talos-commercial migrate up --database "mysql://talos:secret@tcp(db:3306)/talos?parseTime=true"
+```
+
+## TLS / SSL
+
+Use TLS parameters in the DSN for encrypted database connections:
+
+```yaml
+db:
+ dsn: "mysql://talos:secret@tcp(db:3306)/talos?parseTime=true&tls=true"
+```
+
+| Parameter | Description |
+| ----------------- | ---------------------------------------------------------------------- |
+| `tls=true` | Enable TLS with default settings |
+| `tls=skip-verify` | TLS without certificate verification |
+| `tls=custom` | Use custom TLS configuration registered with `mysql.RegisterTLSConfig` |
+
+## Example DSNs
+
+**Development:**
+
+```
+mysql://talos:secret@tcp(localhost:3306)/talos?parseTime=true
+```
+
+**Production with pooling:**
+
+```
+mysql://talos:secret@tcp(db:3306)/talos?parseTime=true&tls=true&max_conns=25&max_idle_conns=5&max_conn_lifetime=5m&max_conn_idle_time=1m
+```
+
+**With timeouts:**
+
+```
+mysql://talos:secret@tcp(db:3306)/talos?parseTime=true&tls=true&timeout=10s&readTimeout=30s&writeTimeout=30s&max_conns=25
+```
diff --git a/docs/talos/operate/database/postgresql.md b/docs/talos/operate/database/postgresql.md
new file mode 100644
index 0000000000..f482a5c953
--- /dev/null
+++ b/docs/talos/operate/database/postgresql.md
@@ -0,0 +1,177 @@
+---
+title: PostgreSQL
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# PostgreSQL
+
+PostgreSQL is the recommended production database backend. It provides connection pooling, ACID
+transactions, and high-availability via streaming replication.
+
+## Supported versions
+
+PostgreSQL 14 and later.
+
+## Configuration
+
+```yaml
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?sslmode=require&max_conns=25&max_conn_lifetime=5m"
+```
+
+Or via environment variable:
+
+```bash
+export TALOS_DB_DSN="postgres://talos:secret@db:5432/talos?sslmode=require&max_conns=25&max_conn_lifetime=5m"
+```
+
+## DSN format
+
+```
+postgres://user:password@host:port/dbname?param=value¶m=value
+```
+
+Both `postgres://` and `postgresql://` schemes are accepted.
+
+## DSN parameters
+
+### Connection pool parameters
+
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
+database driver.
+
+| Parameter | Type | Default | Description |
+| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
+| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
+| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
+| `max_conn_lifetime` | duration | `0` (unlimited) | Maximum age of a connection before it is closed and replaced |
+| `max_conn_idle_time` | duration | `0` (unlimited) | Maximum time a connection can sit idle before it is closed |
+| `pool_mode` | string | `standard` | Pool implementation: `standard` or `advanced` (see below) |
+
+Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
+
+### PostgreSQL driver parameters
+
+These parameters are passed through to the underlying PostgreSQL driver (`pgx`).
+
+| Parameter | Description | Recommended |
+| ------------------ | ----------------------------------------------------------- | ------------- |
+| `sslmode` | TLS mode (`disable`, `require`, `verify-ca`, `verify-full`) | `verify-full` |
+| `sslrootcert` | Path to CA certificate file | — |
+| `sslcert` | Path to client certificate file (for mTLS) | — |
+| `sslkey` | Path to client private key file (for mTLS) | — |
+| `connect_timeout` | Connection timeout in seconds | `10` |
+| `application_name` | Application name reported to PostgreSQL | — |
+
+## Connection pooling
+
+Talos supports two pool modes for PostgreSQL, controlled by the `pool_mode` DSN parameter.
+
+### Standard mode (default)
+
+Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with
+all tooling.
+
+```yaml
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?max_conns=25&max_idle_conns=5&max_conn_lifetime=5m&max_conn_idle_time=1m"
+```
+
+Pool behavior:
+
+- Connections are created on demand up to `max_conns`
+- Idle connections are kept up to `max_idle_conns`
+- Connections older than `max_conn_lifetime` are closed and replaced
+- Connections idle longer than `max_conn_idle_time` are closed
+
+### Advanced mode
+
+Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is
+optimized for Kubernetes and cloud environments.
+
+```yaml
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?pool_mode=advanced"
+```
+
+In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the DSN.
+The `max_conns`, `max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters are not
+used — pgxpool manages its own pool.
+
+Use advanced mode when:
+
+- Running in Kubernetes with connection health checks
+- Using cloud-managed PostgreSQL (RDS, Cloud SQL, AlloyDB) with aggressive connection recycling
+- Deploying with PgBouncer and needing precise pool control
+
+## Pool sizing
+
+Start with 25 connections per instance. The total pool across all instances must stay below
+PostgreSQL's `max_connections` (default: 100).
+
+| Deployment | `max_conns` | Notes |
+| --------------- | -------------- | ------------------------------------------- |
+| Single instance | `25` | Good starting point |
+| 3 instances | `25` each | 75 total — within default `max_connections` |
+| 5+ instances | `15`–`20` each | Use PgBouncer to multiplex connections |
+
+For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL.
+PgBouncer multiplexes many application connections over fewer database connections, allowing you to
+scale beyond PostgreSQL's connection limit.
+
+## Migrations
+
+```bash
+talos-commercial migrate up --database "postgres://talos:secret@db:5432/talos"
+```
+
+## TLS / SSL
+
+Use the `sslmode` parameter in the DSN for encrypted database connections:
+
+```yaml
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt"
+```
+
+| Mode | Description |
+| ------------- | --------------------------------------------------- |
+| `disable` | No TLS |
+| `require` | TLS without certificate verification |
+| `verify-ca` | TLS with CA verification |
+| `verify-full` | TLS with CA and hostname verification (recommended) |
+
+For mutual TLS (mTLS), provide both client certificate and key:
+
+```yaml
+db:
+ dsn: "postgres://talos:secret@db:5432/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt&sslcert=/certs/client.crt&sslkey=/certs/client.key"
+```
+
+## Example DSNs
+
+**Development:**
+
+```
+postgres://talos:secret@localhost:5432/talos?sslmode=disable
+```
+
+**Production with standard pooling:**
+
+```
+postgres://talos:secret@db:5432/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt&max_conns=25&max_idle_conns=5&max_conn_lifetime=5m&max_conn_idle_time=1m
+```
+
+**Production with advanced pooling (Kubernetes):**
+
+```
+postgres://talos:secret@db:5432/talos?sslmode=verify-full&sslrootcert=/certs/ca.crt&pool_mode=advanced
+```
+
+**Behind PgBouncer:**
+
+```
+postgres://talos:secret@pgbouncer:6432/talos?sslmode=require&max_conns=50&max_idle_conns=10&max_conn_lifetime=5m
+```
diff --git a/docs/talos/operate/database/sqlite.md b/docs/talos/operate/database/sqlite.md
new file mode 100644
index 0000000000..1778d5dbb2
--- /dev/null
+++ b/docs/talos/operate/database/sqlite.md
@@ -0,0 +1,29 @@
+---
+title: SQLite
+---
+
+# SQLite
+
+SQLite is the default database for the OSS edition. It requires no external dependencies.
+
+## Configuration
+
+```yaml
+db:
+ dsn: "sqlite:///var/lib/talos/data.db"
+```
+
+Talos enables WAL mode automatically for better concurrency.
+
+## Migrations
+
+```bash
+talos migrate up --database "sqlite:///var/lib/talos/data.db"
+```
+
+## Limitations
+
+- Single-node only (no multi-instance deployments)
+- No connection pooling (single-writer lock)
+- Write throughput limited by disk I/O
+- Not suitable for [separate admin/data planes](../deploy/separate-planes.md) unless co-located
diff --git a/docs/talos/operate/deploy/docker.md b/docs/talos/operate/deploy/docker.md
new file mode 100644
index 0000000000..24bac56ed0
--- /dev/null
+++ b/docs/talos/operate/deploy/docker.md
@@ -0,0 +1,67 @@
+---
+title: Docker
+---
+
+# Docker
+
+## Quick start
+
+```bash
+docker run -d \
+ -p 4420:4420 \
+ -e TALOS_SECRETS_DEFAULT_CURRENT="my-secret-must-be-at-least-32-characters-long" \
+ -e TALOS_CREDENTIALS_ISSUER="http://localhost:4420" \
+ -e TALOS_DB_DSN="sqlite:///data/talos.db" \
+ -v talos-data:/data \
+ oryd/talos:latest serve
+```
+
+## With config file
+
+```bash
+docker run -d \
+ -p 4420:4420 \
+ -v ./config.yaml:/etc/talos/config.yaml \
+ -v talos-data:/data \
+ oryd/talos:latest serve --config /etc/talos/config.yaml
+```
+
+## Run migrations
+
+```bash
+docker run --rm \
+ -v talos-data:/data \
+ oryd/talos:latest migrate up --database "sqlite:///data/talos.db"
+```
+
+## Health check
+
+```yaml
+healthcheck:
+ test: ["CMD", "curl", "-sf", "http://localhost:4420/health/alive"]
+ interval: 10s
+ timeout: 5s
+ retries: 3
+```
+
+## Docker Compose
+
+```yaml
+services:
+ talos:
+ image: oryd/talos:latest
+ command: serve --config /etc/talos/config.yaml
+ ports:
+ - "4420:4420"
+ volumes:
+ - ./config.yaml:/etc/talos/config.yaml
+ - talos-data:/data
+ healthcheck:
+ test: ["CMD", "curl", "-sf", "http://localhost:4420/health/alive"]
+ interval: 10s
+ timeout: 5s
+ retries: 3
+
+volumes:
+ talos-data:
+```
diff --git a/docs/talos/operate/deploy/edge-proxy.md b/docs/talos/operate/deploy/edge-proxy.md
new file mode 100644
index 0000000000..62a1dc690c
--- /dev/null
+++ b/docs/talos/operate/deploy/edge-proxy.md
@@ -0,0 +1,277 @@
+---
+title: Edge proxy
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# Edge proxy
+
+Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification
+latency.
+
+## Pattern
+
+```mermaid
+graph TB
+ subgraph edgeA["Edge Region A"]
+ dpA["Data Plane
+ Cache"]
+ end
+
+ subgraph edgeB["Edge Region B"]
+ dpB["Data Plane
+ Cache"]
+ end
+
+ subgraph core["Core Data Center"]
+ admin["Admin Plane"]
+ end
+
+ dpA -- shared DB --> db[("Database")]
+ dpB -- shared DB --> db
+ admin --> db
+```
+
+## Benefits
+
+- Verification latency matches the distance to the nearest edge node
+- Cache absorbs repeated lookups, reducing database load
+- Admin operations remain centralized and secured
+
+## How it works
+
+The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos
+server. It intercepts `POST` requests to `/v2/verify/*` endpoints, caches positive (active)
+verification responses locally, and proxies everything else to upstream unchanged.
+
+```mermaid
+sequenceDiagram
+ participant App
+ participant Proxy as Edge Proxy
+ participant Talos as Upstream Talos
+
+ App->>Proxy: POST /v2/verify/apiKey
+ alt Cache HIT
+ Proxy-->>App: 200 OK (cached, sub-ms)
+ else Cache MISS
+ Proxy->>Talos: POST /v2/verify/apiKey
+ Talos-->>Proxy: 200 OK (active=true)
+ Note over Proxy: Cache response
+ Proxy-->>App: 200 OK
+ end
+ App->>Proxy: POST /v2/admin/issuedApiKeys
+ Proxy->>Talos: Proxy unchanged
+ Talos-->>Proxy: 200 OK
+ Proxy-->>App: 200 OK
+```
+
+Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the
+proxy transparently.
+
+## Sidecar deployment
+
+Run the proxy as a sidecar container alongside your application. Your application sends verify
+requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
+
+```
+┌─────────────────────────────────┐
+│ Pod / VM / Task │
+│ │
+│ ┌───────────┐ ┌───────────┐ │
+│ │ App │──▶│ Proxy │─┼──▶ Upstream Talos
+│ │ │ │ :8080 │ │
+│ └───────────┘ └───────────┘ │
+└─────────────────────────────────┘
+```
+
+Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy
+listens on). All other Talos API calls (admin, key management) should go directly to the central
+server.
+
+## Configuration
+
+Start the proxy with `talos-commercial proxy`:
+
+```bash
+talos-commercial proxy \
+ --upstream http://talos-central:8080 \
+ --listen :9090 \
+ --cache-ttl 60s \
+ --cache-max-size 104857600
+```
+
+| Flag | Default | Description |
+| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `--upstream` | _(required)_ | URL of the upstream Talos server. |
+| `--listen` | `:8080` | Address and port the proxy listens on. |
+| `--cache-ttl` | `60s` | Default TTL for cached verification responses. |
+| `--cache-max-size` | `104857600` (100 MB) | Maximum in-memory cache size in bytes. |
+| `--cache-num-counters` | `10000` | Number of frequency counters for cache admission policy. Higher values improve hit rates for large working sets. |
+| `--trust-x-forwarded-host` | `false` | Use `X-Forwarded-Host` header for tenant-aware cache keys. Enable only when the proxy runs behind a trusted load balancer. |
+| `--allowed-hosts` | _(none)_ | Comma-separated allowlist of valid `Host` / `X-Forwarded-Host` values. Requests with other hosts are rejected with `403 Forbidden`. |
+
+## Cache behavior
+
+### Cache key generation
+
+Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent
+collision attacks. The host component ensures tenant isolation in multi-tenant deployments: the same
+credential cached under `tenant-a.example.com` will not be served for requests from
+`tenant-b.example.com`.
+
+### What gets cached
+
+Only responses that meet **all** of the following criteria are cached:
+
+- The request is a `POST` to `/v2/verify/*`
+- The upstream returned HTTP `200 OK`
+- The response body contains `"is_active": true`
+
+Inactive credentials, error responses, and non-verify endpoints are never cached.
+
+### TTL calculation
+
+The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the
+verification response includes an `expires_at` timestamp, the proxy ensures the cached entry expires
+no later than the credential itself. If `expires_at` is absent, the configured `--cache-ttl` is
+used.
+
+### Cache headers
+
+Every response from the proxy includes an `Ory-Talos-Cache` header:
+
+| Header value | Meaning |
+| ------------ | ------------------------------------------------------------------------------ |
+| `HIT` | Response served from local cache. |
+| `MISS` | Response fetched from upstream (may have been cached for subsequent requests). |
+
+### Cache bypass
+
+Clients can bypass the cache by including a `Cache-Control` header:
+
+```bash
+curl -X POST http://localhost:8080/v2/verify/apiKey \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d '{"credential": "phx_..."}'
+```
+
+Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for
+caching.
+
+## Health checks
+
+The proxy exposes the following health endpoints:
+
+| Endpoint | Behavior |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/health/alive` | Always returns `200 OK`. Use as a liveness probe. |
+| `/health/ready` | Checks upstream connectivity by calling the upstream's `/health/alive` endpoint. Returns `200 OK` if upstream is reachable, `503 Service Unavailable` otherwise. Use as a readiness probe. |
+| `/metrics` | Prometheus metrics endpoint. |
+
+## Proxy metrics
+
+The proxy exposes Prometheus metrics under the `talos_proxy_` namespace:
+
+| Metric | Type | Description |
+| -------------------------------------- | --------- | ------------------------------------------------------------- |
+| `talos_proxy_cache_hits_total` | Counter | Total number of cache hits. |
+| `talos_proxy_cache_misses_total` | Counter | Total number of cache misses. |
+| `talos_proxy_upstream_requests_total` | Counter | Requests forwarded to upstream, labeled by `status` code. |
+| `talos_proxy_upstream_latency_seconds` | Histogram | Latency of upstream requests. |
+| `talos_proxy_request_duration_seconds` | Histogram | Total request duration, labeled by `cached` (`true`/`false`). |
+
+For general monitoring guidance, see [Metrics](../monitoring/metrics.md).
+
+## Docker Compose sidecar example
+
+```yaml
+services:
+ talos:
+ image: oryd/talos-commercial:latest
+ command: serve
+ ports:
+ - "8080:8080"
+ environment:
+ - DATABASE_URL=postgres://talos:secret@db:5432/talos?sslmode=disable
+
+ proxy:
+ image: oryd/talos-commercial:latest
+ command: >
+ proxy --upstream http://talos:8080 --listen :9090 --cache-ttl 60s
+ ports:
+ - "9090:9090"
+
+ app:
+ image: your-app:latest
+ environment:
+ # Verify requests go through the local proxy
+ - TALOS_VERIFY_URL=http://proxy:9090
+ # Admin requests go directly to the central server
+ - TALOS_ADMIN_URL=http://talos:8080
+ depends_on:
+ - proxy
+ - talos
+```
+
+## Kubernetes sidecar example
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+ name: app-with-talos-proxy
+spec:
+ containers:
+ - name: app
+ image: your-app:latest
+ env:
+ # Verify requests go through the localhost sidecar
+ - name: TALOS_VERIFY_URL
+ value: "http://localhost:9090"
+ # Admin requests go directly to the central server
+ - name: TALOS_ADMIN_URL
+ value: "http://talos.talos-system.svc.cluster.local:8080"
+
+ - name: talos-proxy
+ image: oryd/talos-commercial:latest
+ args:
+ - proxy
+ - --upstream
+ - http://talos.talos-system.svc.cluster.local:8080
+ - --listen
+ - :9090
+ - --cache-ttl
+ - "60s"
+ ports:
+ - containerPort: 9090
+ name: proxy
+ livenessProbe:
+ httpGet:
+ path: /health/alive
+ port: proxy
+ initialDelaySeconds: 2
+ periodSeconds: 10
+ readinessProbe:
+ httpGet:
+ path: /health/ready
+ port: proxy
+ initialDelaySeconds: 5
+ periodSeconds: 10
+ resources:
+ requests:
+ memory: "64Mi"
+ cpu: "50m"
+ limits:
+ memory: "256Mi"
+ cpu: "200m"
+```
+
+## Eventual consistency
+
+Revocation takes effect in the database immediately but cached verification results persist until
+the cache TTL expires. To force an immediate re-check against upstream, send
+`Cache-Control: no-cache` on the verification request.
+
+Choose a `--cache-ttl` that balances latency savings against your revocation propagation
+requirements. Shorter TTLs provide faster revocation propagation at the cost of more upstream
+requests.
diff --git a/docs/talos/operate/deploy/index.md b/docs/talos/operate/deploy/index.md
new file mode 100644
index 0000000000..b70d601bff
--- /dev/null
+++ b/docs/talos/operate/deploy/index.md
@@ -0,0 +1,23 @@
+---
+title: Deploy
+---
+
+# Deploy
+
+Talos can be deployed as a standalone binary, Docker container, or Kubernetes workload.
+
+## Deployment options
+
+| Method | Best for |
+| --------------------------- | ----------------------------------- |
+| [Docker](docker.md) | Development, small-scale production |
+| [Kubernetes](kubernetes.md) | Production with orchestration |
+| Binary | Custom deployments |
+
+## Architecture options
+
+| Topology | Edition | Description |
+| ------------------------------------- | ---------- | --------------------------------------------- |
+| Single-node | OSS | One process serves both admin and data planes |
+| [Separate planes](separate-planes.md) | Commercial | Independent admin and data plane deployments |
+| [Edge proxy](edge-proxy.md) | Commercial | Data plane at the edge, admin plane in core |
diff --git a/docs/talos/operate/deploy/kubernetes.md b/docs/talos/operate/deploy/kubernetes.md
new file mode 100644
index 0000000000..f0598a974d
--- /dev/null
+++ b/docs/talos/operate/deploy/kubernetes.md
@@ -0,0 +1,117 @@
+---
+title: Kubernetes
+---
+
+# Kubernetes
+
+## Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: talos
+spec:
+ replicas: 3
+ selector:
+ matchLabels:
+ app: talos
+ template:
+ metadata:
+ labels:
+ app: talos
+ spec:
+ initContainers:
+ - name: migrate
+ image: oryd/talos:latest
+ command: ["talos", "migrate", "up"]
+ env:
+ - name: TALOS_DB_DSN
+ valueFrom:
+ secretKeyRef:
+ name: talos-secrets
+ key: dsn
+ containers:
+ - name: talos
+ image: oryd/talos:latest
+ args: ["serve", "--config", "/etc/talos/config.yaml"]
+ ports:
+ - containerPort: 4420
+ name: http
+ - containerPort: 4422
+ name: metrics
+ livenessProbe:
+ httpGet:
+ path: /health/alive
+ port: http
+ initialDelaySeconds: 5
+ periodSeconds: 10
+ readinessProbe:
+ httpGet:
+ path: /health/ready
+ port: http
+ initialDelaySeconds: 5
+ periodSeconds: 10
+ env:
+ - name: TALOS_DB_DSN
+ valueFrom:
+ secretKeyRef:
+ name: talos-secrets
+ key: dsn
+ - name: TALOS_SECRETS_DEFAULT_CURRENT
+ valueFrom:
+ secretKeyRef:
+ name: talos-secrets
+ key: hmac-secret
+ - name: TALOS_CREDENTIALS_ISSUER
+ value: "https://api.example.com"
+ volumeMounts:
+ - name: config
+ mountPath: /etc/talos
+ volumes:
+ - name: config
+ configMap:
+ name: talos-config
+```
+
+## Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+ name: talos
+spec:
+ selector:
+ app: talos
+ ports:
+ - name: http
+ port: 4420
+ - name: metrics
+ port: 4422
+```
+
+## Horizontal Pod Autoscaler
+
+Scale based on CPU or request rate:
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+ name: talos
+spec:
+ scaleTargetRef:
+ apiVersion: apps/v1
+ kind: Deployment
+ name: talos
+ minReplicas: 3
+ maxReplicas: 20
+ metrics:
+ - type: Resource
+ resource:
+ name: cpu
+ target:
+ type: Utilization
+ averageUtilization: 70
+```
diff --git a/docs/talos/operate/deploy/separate-planes.md b/docs/talos/operate/deploy/separate-planes.md
new file mode 100644
index 0000000000..ed30a29b44
--- /dev/null
+++ b/docs/talos/operate/deploy/separate-planes.md
@@ -0,0 +1,83 @@
+---
+title: Separate admin and data planes
+---
+
+# Separate admin and data planes
+
+In production, you can deploy the admin plane and data plane as separate processes for independent
+scaling and security isolation.
+
+## Why separate
+
+- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be
+ exposed at the edge
+- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane
+ handles lower-volume management
+- **Network isolation**: Admin plane behind internal firewall; data plane behind public load
+ balancer
+
+## Architecture
+
+Both planes share the same database. The admin plane writes keys; the data plane reads and verifies
+them.
+
+```mermaid
+graph TB
+ subgraph internal["Internal Network"]
+ admin["Admin Plane (× N)
Issue keys
Revoke keys
Derive tokens"]
+ end
+
+ subgraph public["Public Network"]
+ data["Data Plane (× N)
Verify keys
Self-revoke
Batch verify"]
+ end
+
+ admin -- shared DB --> db[("Database")]
+ data -- shared DB --> db
+ data --> cache["Cache (optional)"]
+```
+
+## Commands
+
+Talos provides separate subcommands for each plane:
+
+```bash
+# Run both planes in a single process (development/small deployments)
+talos serve --config config.yaml
+
+# Run only the admin plane (key management, token derivation)
+talos serve admin --config config.yaml
+
+# Run only the data plane (verification, self-revocation, caching)
+talos serve check --config config.yaml
+```
+
+## Configuration
+
+Both deployments use the same config file or environment variables. The key difference is network
+exposure:
+
+**Admin plane** — bind to internal network only:
+
+```yaml
+serve:
+ http:
+ host: "10.0.0.1"
+ port: 4420
+```
+
+**Data plane** — bind to all interfaces with caching:
+
+```yaml
+serve:
+ http:
+ host: "0.0.0.0"
+ port: 4420
+cache:
+ type: "memory"
+ ttl: "5m"
+```
+
+## Network policies
+
+Restrict admin plane access to internal services only. Data plane can accept traffic from any
+source.
diff --git a/docs/talos/operate/index.md b/docs/talos/operate/index.md
new file mode 100644
index 0000000000..37e92dafb1
--- /dev/null
+++ b/docs/talos/operate/index.md
@@ -0,0 +1,47 @@
+---
+title: Operate
+description: Install, configure, and deploy Ory Talos
+---
+
+# Operate Ory Talos
+
+This section covers everything platform engineers need to run Talos in production.
+
+## Getting started
+
+1. **[Install](install.md)** — build from source or download a binary
+2. **[Configure](configure.md)** — set up the config file, environment variables, and secrets
+3. **[Database](database/index.md)** — choose and configure a database backend
+4. **[Deploy](deploy/index.md)** — run Talos with Docker, Kubernetes, or as a systemd service
+
+## Production checklist
+
+Before going to production, review these guides:
+
+- **[Secrets management](secrets.md)** — configure HMAC secrets and JWKS signing keys
+- **[TLS](tls.md)** — enable TLS termination or configure a reverse proxy
+- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and
+ health checks
+- **[Security hardening](security-hardening.md)** — production security checklist
+- **[Benchmarks](benchmarks.md)** — performance baselines and load testing
+
+## Commercial features
+
+These features require the Commercial edition:
+
+- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**,
+ **[CockroachDB](database/cockroachdb.md)** — production-grade SQL backends
+- **[Caching](cache/index.md)** — in-memory and Redis caching for sub-millisecond verification
+- **[Edge proxy](deploy/edge-proxy.md)** — deploy data plane at the edge
+- **[Multi-tenancy](multi-tenancy.md)** — serve multiple tenants from a single cluster
+
+## Architecture
+
+Talos separates administrative operations (issuing, revoking) from verification:
+
+- **Admin plane** — manages key lifecycle. Runs behind your internal network.
+- **Data plane** — verifies credentials at the edge. Horizontally scalable with caching.
+
+You can run both planes in a single process (`talos serve`) or split them for production
+(`talos serve admin`, `talos serve check`). See [Separate planes](deploy/separate-planes.md) for
+details.
diff --git a/docs/talos/operate/install.md b/docs/talos/operate/install.md
new file mode 100644
index 0000000000..08e2d43961
--- /dev/null
+++ b/docs/talos/operate/install.md
@@ -0,0 +1,70 @@
+---
+title: Install
+description: Build Talos from source or download a pre-built binary
+---
+
+# Install
+
+
+
+## Build from source
+
+Talos requires Go 1.23 or later.
+
+### OSS edition
+
+```bash
+git clone https://github.com/ory/talos.git
+cd talos
+go build -o .bin/talos .
+```
+
+The binary is at `.bin/talos`. SQLite is the only supported database backend in the OSS edition.
+
+### Commercial edition
+
+The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin
+UI:
+
+```bash
+go build -tags commercial -o .bin/talos-commercial .
+```
+
+## Verify the installation
+
+
+
+```bash
+./.bin/talos version
+./.bin/talos help
+```
+
+## Run database migrations
+
+Before starting the server, run migrations to create the database schema:
+
+```bash
+# SQLite (OSS)
+./.bin/talos migrate up --database "sqlite:///path/to/talos.db"
+
+# PostgreSQL (Commercial)
+./.bin/talos-commercial migrate up --database "postgres://user:pass@localhost:5432/talos"
+
+# MySQL (Commercial)
+./.bin/talos-commercial migrate up --database "mysql://user:pass@tcp(localhost:3306)/talos"
+
+# CockroachDB (Commercial)
+./.bin/talos-commercial migrate up --database "cockroach://user@localhost:26257/talos"
+```
+
+## Start the server
+
+```bash
+./.bin/talos serve --config config.yaml
+```
+
+See [Configure](configure.md) for config file format and options.
+
+## Docker
+
+See [Docker deployment](deploy/docker.md) for running Talos in containers.
diff --git a/docs/talos/operate/monitoring/health-checks.md b/docs/talos/operate/monitoring/health-checks.md
new file mode 100644
index 0000000000..eec21edfee
--- /dev/null
+++ b/docs/talos/operate/monitoring/health-checks.md
@@ -0,0 +1,49 @@
+---
+title: Health checks
+---
+
+# Health checks
+
+Talos exposes three health endpoints on the main HTTP port.
+
+## Endpoints
+
+| Endpoint | Purpose | Use for |
+| --------------- | --------------- | ------------------------------------------ |
+| `/health/alive` | Liveness probe | Kubernetes `livenessProbe` |
+| `/health/ready` | Readiness probe | Kubernetes `readinessProbe`, load balancer |
+| `/health` | Combined health | Quick manual checks |
+
+## Kubernetes probes
+
+```yaml
+livenessProbe:
+ httpGet:
+ path: /health/alive
+ port: 4420
+ initialDelaySeconds: 5
+ periodSeconds: 10
+
+readinessProbe:
+ httpGet:
+ path: /health/ready
+ port: 4420
+ initialDelaySeconds: 5
+ periodSeconds: 10
+```
+
+## Load balancer
+
+Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server
+is ready to accept traffic and 503 when it is not (e.g., during startup or shutdown).
+
+## Suppressing health logs
+
+To reduce log noise from frequent health checks:
+
+```yaml
+serve:
+ http:
+ request_log:
+ exclude_health_endpoints: true
+```
diff --git a/docs/talos/operate/monitoring/index.md b/docs/talos/operate/monitoring/index.md
new file mode 100644
index 0000000000..003e735225
--- /dev/null
+++ b/docs/talos/operate/monitoring/index.md
@@ -0,0 +1,12 @@
+---
+title: Monitoring
+---
+
+# Monitoring
+
+Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health
+endpoints.
+
+- [Prometheus metrics](metrics.md) — request counts, latencies, and pool sizes
+- [OpenTelemetry tracing](tracing.md) — distributed request traces
+- [Health checks](health-checks.md) — liveness and readiness probes
diff --git a/docs/talos/operate/monitoring/metrics.md b/docs/talos/operate/monitoring/metrics.md
new file mode 100644
index 0000000000..6f626d23ff
--- /dev/null
+++ b/docs/talos/operate/monitoring/metrics.md
@@ -0,0 +1,67 @@
+---
+title: Prometheus metrics
+---
+
+# Prometheus metrics
+
+Talos exposes Prometheus metrics on a dedicated port (default: 4422).
+
+## Endpoint
+
+```
+GET http://localhost:4422/metrics
+```
+
+## HTTP metrics
+
+| Metric | Type | Labels | Description |
+| ------------------------------- | --------- | ---------------------------- | --------------------- |
+| `http_requests_total` | Counter | `method`, `code`, `endpoint` | Total HTTP requests |
+| `http_request_duration_seconds` | Histogram | `method`, `code`, `endpoint` | Request latency |
+| `http_request_size_bytes` | Histogram | `method`, `code` | Request payload size |
+| `http_response_size_bytes` | Histogram | `method`, `code` | Response payload size |
+| `http_requests_in_flight` | Gauge | -- | Concurrent requests |
+
+### Labels
+
+| Label | Description | Used by |
+| ---------- | --------------------------------------------------------- | ------------------------------------------------------ |
+| `method` | HTTP method (lowercase) | All except `http_requests_in_flight` |
+| `code` | HTTP status code | All except `http_requests_in_flight` |
+| `endpoint` | Route template (e.g., `/v2/admin/issuedApiKeys/{key_id}`) | `http_requests_total`, `http_request_duration_seconds` |
+
+## Configuration
+
+```yaml
+serve:
+ metrics:
+ host: "0.0.0.0"
+ port: 4422
+```
+
+## Proxy metrics (Commercial)
+
+The edge proxy exposes additional metrics under the `talos_proxy_` namespace.
+
+| Metric | Type | Labels | Description |
+| -------------------------------------- | --------- | -------- | ------------------------------ |
+| `talos_proxy_cache_hits_total` | Counter | -- | Total number of cache hits |
+| `talos_proxy_cache_misses_total` | Counter | -- | Total number of cache misses |
+| `talos_proxy_upstream_requests_total` | Counter | `status` | Requests forwarded to upstream |
+| `talos_proxy_upstream_latency_seconds` | Histogram | -- | Upstream request latency |
+| `talos_proxy_request_duration_seconds` | Histogram | `cached` | Total request duration |
+
+### Labels
+
+| Label | Description | Used by |
+| -------- | ----------------------------------------------------------- | -------------------------------------- |
+| `status` | HTTP status code of upstream response | `talos_proxy_upstream_requests_total` |
+| `cached` | Whether the response was served from cache (`true`/`false`) | `talos_proxy_request_duration_seconds` |
+
+## Grafana
+
+Scrape the metrics endpoint with Prometheus and visualize with Grafana. Key panels:
+
+- Request rate: `rate(http_requests_total[5m])`
+- P99 latency: `histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))`
+- Error rate: `rate(http_requests_total{code=~"5.."}[5m])`
diff --git a/docs/talos/operate/monitoring/tracing.md b/docs/talos/operate/monitoring/tracing.md
new file mode 100644
index 0000000000..9bb00521b5
--- /dev/null
+++ b/docs/talos/operate/monitoring/tracing.md
@@ -0,0 +1,41 @@
+---
+title: OpenTelemetry tracing
+---
+
+# OpenTelemetry tracing
+
+Talos supports distributed tracing via OpenTelemetry.
+
+## Configuration
+
+```yaml
+tracing:
+ enabled: true
+ service_name: "talos"
+ exporter: "otlp"
+ endpoint: "otel-collector:4317"
+ sample_rate: 0.01
+```
+
+## Exporters
+
+| Exporter | Description |
+| -------- | ------------------------------------ |
+| `otlp` | OpenTelemetry Protocol (recommended) |
+| `jaeger` | Jaeger native format |
+| `stdout` | Print traces to stderr (debugging) |
+
+## Environment variables
+
+```bash
+export TALOS_TRACING_ENABLED=true
+export TALOS_TRACING_EXPORTER=otlp
+export TALOS_TRACING_ENDPOINT=otel-collector:4317
+export TALOS_TRACING_SAMPLE_RATE=0.01
+```
+
+## Traced operations
+
+Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP
+request handling. Each trace includes the Network ID (for multi-tenant deployments) and relevant key
+identifiers.
diff --git a/docs/talos/operate/multi-tenancy.md b/docs/talos/operate/multi-tenancy.md
new file mode 100644
index 0000000000..7094b4e298
--- /dev/null
+++ b/docs/talos/operate/multi-tenancy.md
@@ -0,0 +1,47 @@
+---
+title: Multi-tenancy
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+# Multi-tenancy
+
+Talos supports multi-tenancy through Network IDs (NID) derived from the request hostname.
+
+## How it works
+
+1. Each tenant is assigned a unique Network ID
+2. The hostname middleware extracts the NID from the incoming request's hostname
+3. All database operations are scoped to the NID via composite primary keys `(nid, key_id)`
+4. Keys created in one tenant cannot be accessed or verified in another
+
+## Configuration
+
+```yaml
+multitenancy:
+ enabled: true
+ networks:
+ - hostname: "tenant1.talos.example.com"
+ id: "550e8400-e29b-41d4-a716-446655440001"
+ config_path: "/etc/talos/tenant1.yaml"
+ - hostname: "tenant2.talos.example.com"
+ id: "550e8400-e29b-41d4-a716-446655440002"
+ config_path: "/etc/talos/tenant2.yaml"
+```
+
+Each entry maps a hostname to a network. The `hostname` is matched against the incoming request's
+`Host` / `X-Forwarded-Host` header (port is stripped before comparison). The `id` is the tenant's
+UUID. The `config_path` points to a network-specific configuration file (absolute or relative to the
+working directory).
+
+## Database isolation
+
+Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every
+query includes the NID, ensuring complete data isolation at the SQL level.
+
+## Defense-in-depth
+
+Token claims embed the NID at derivation time. During verification, the claim NID is validated
+against the context NID (from hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`,
+preventing cross-tenant token replay.
diff --git a/docs/talos/operate/secrets.md b/docs/talos/operate/secrets.md
new file mode 100644
index 0000000000..cd62b34281
--- /dev/null
+++ b/docs/talos/operate/secrets.md
@@ -0,0 +1,54 @@
+---
+title: Secret management
+---
+
+# Secret management
+
+Talos uses HMAC secrets for API key checksum generation and verification.
+
+## Configuration
+
+```yaml
+secrets:
+ default:
+ current: "a-32-byte-or-longer-secret-here!"
+ retired:
+ - "previous-secret-that-was-rotated"
+ hmac:
+ current: "optional-separate-hmac-secret-32chars"
+ retired: []
+```
+
+## Secret types
+
+| Secret | Purpose | Required |
+| ------------------------- | ----------------------------------------- | ------------------ |
+| `secrets.default.current` | Default secret for HMAC and pagination | Yes (min 32 chars) |
+| `secrets.hmac.current` | Dedicated HMAC secret (overrides default) | No |
+
+If `secrets.hmac.current` is not set, Talos falls back to `secrets.default.current`.
+
+## Secret rotation
+
+1. Add the current secret to the `retired` array
+2. Set a new `current` secret
+3. Restart Talos (or wait for config hot-reload)
+
+```yaml
+secrets:
+ default:
+ current: "new-secret-32-chars-minimum-here!"
+ retired:
+ - "old-secret-that-was-previously-current"
+```
+
+During verification, Talos tries the current secret first, then each retired secret in order. This
+ensures existing API keys remain valid after rotation.
+
+## Environment variables
+
+```bash
+export TALOS_SECRETS_DEFAULT_CURRENT="my-secret-32-chars-minimum"
+export TALOS_SECRETS_DEFAULT_RETIRED="old-secret-1,old-secret-2"
+export TALOS_SECRETS_HMAC_CURRENT="optional-hmac-secret"
+```
diff --git a/docs/talos/operate/security-hardening.md b/docs/talos/operate/security-hardening.md
new file mode 100644
index 0000000000..41b88027dc
--- /dev/null
+++ b/docs/talos/operate/security-hardening.md
@@ -0,0 +1,39 @@
+---
+title: Security hardening
+---
+
+# Security hardening
+
+## Network
+
+- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance
+ and revocation and should never be exposed to the public internet.
+- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or
+ terminate TLS at the load balancer).
+- **Separate admin and data planes** in production for independent security boundaries.
+
+## Secrets
+
+- **Use strong HMAC secrets** of at least 32 characters, generated with a cryptographically secure
+ random generator.
+- **Use separate HMAC secrets** (`secrets.hmac.current`) rather than relying on the default secret.
+- **Rotate secrets regularly** using the retired array. Verification tries current + retired secrets
+ automatically.
+- **Never commit secrets** to version control. Use environment variables or a secrets manager.
+
+## API keys
+
+- **Set TTL on all keys** to limit exposure from leaked credentials.
+- **Revoke compromised keys immediately** using `POST /v2/admin/apiKeys/{id}:revoke`.
+- **Use scopes** to limit key permissions to the minimum required.
+
+## Caching
+
+- **Enable caching** to protect the database from verification floods (DoS).
+- **Set appropriate TTL** balancing latency of revocation propagation vs. database load.
+
+## Monitoring
+
+- **Monitor verification error rates** for anomalous patterns (credential stuffing, brute force).
+- **Enable tracing** to audit key usage and identify suspicious activity.
+- **Set up alerts** on `http_requests_total{code=~"4.."}` and `http_requests_total{code=~"5.."}`.
diff --git a/docs/talos/operate/tls.md b/docs/talos/operate/tls.md
new file mode 100644
index 0000000000..6e630b71ba
--- /dev/null
+++ b/docs/talos/operate/tls.md
@@ -0,0 +1,18 @@
+---
+title: TLS configuration
+---
+
+# TLS configuration
+
+Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy,
+Caddy) for TLS termination:
+
+```
+Client --[HTTPS]--> Load Balancer --[HTTP]--> Talos
+```
+
+For database connection encryption, see the TLS section in each database guide:
+
+- [PostgreSQL TLS](database/postgresql.md#tls--ssl)
+- [MySQL TLS](database/mysql.md#tls--ssl)
+- [CockroachDB TLS](database/cockroachdb.md#dsn-parameters-connection-pooling-and-tls)
diff --git a/docs/talos/operate/troubleshooting.md b/docs/talos/operate/troubleshooting.md
new file mode 100644
index 0000000000..fecf8a0a5f
--- /dev/null
+++ b/docs/talos/operate/troubleshooting.md
@@ -0,0 +1,84 @@
+---
+title: Troubleshooting
+---
+
+# Troubleshooting
+
+
+
+
+## Common issues
+
+### Connection refused on port 4420
+
+The server is not running or is bound to a different interface.
+
+
+
+```bash
+# Check if Talos is listening
+curl -sf "$TALOS_URL/health/alive"
+```
+
+Verify `serve.http.host` and `serve.http.port` in your config.
+
+### Migration failures
+
+```bash
+# Check migration status
+talos migrate status --database "sqlite:///path/to/db"
+```
+
+If a migration failed partway through, inspect the database schema and retry with
+`talos migrate up`.
+
+### Secret too short
+
+```
+Error: secret must be at least 32 characters
+```
+
+Set `secrets.default.current` to a string of at least 32 characters.
+
+### Key verification returns not found
+
+1. Verify the key was issued on the same Talos instance (or shared database)
+2. Check if the key has been revoked: `GET /v2/admin/issuedApiKeys/{key_id}`
+3. If using caching, try with `Cache-Control: no-cache` header
+4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was
+ issued
+
+### Invalid API key format
+
+The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret
+(not the key_id) is being sent.
+
+## Debug logging
+
+Enable debug logs for more detail:
+
+```yaml
+log:
+ level: "debug"
+ format: "json"
+```
+
+Or via environment variable:
+
+```bash
+export TALOS_LOG_LEVEL=debug
+```
+
+## Health check debugging
+
+
+
+```bash
+# Liveness
+curl -s "$TALOS_URL/health/alive" | jq .
+
+# Readiness
+curl -s "$TALOS_URL/health/ready" | jq .
+```
+
+If readiness fails, the database connection may be down.
diff --git a/docs/talos/quickstart/docker-commercial.md b/docs/talos/quickstart/docker-commercial.md
new file mode 100644
index 0000000000..7ced0fb435
--- /dev/null
+++ b/docs/talos/quickstart/docker-commercial.md
@@ -0,0 +1,119 @@
+---
+title: Docker quickstart (Commercial)
+tags: [commercial]
+sidebar_custom_props:
+ badge: Commercial
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Docker quickstart (Commercial)
+
+Run the Commercial edition with PostgreSQL and Redis using Docker Compose.
+
+
+
+
+## Start the stack
+
+```bash
+docker compose -f docker-compose.commercial.yaml up -d
+```
+
+This starts Talos, PostgreSQL, and Redis. Migrations run automatically.
+
+## Issue a key
+
+
+
+
+
+
+```bash
+# Note: rate_limit_policy is only available via the HTTP API.
+RESPONSE=$(talos keys issue "commercial-test" \
+ --actor user_1 \
+ --scopes "read,write" \
+ --ttl 168h \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "commercial-test",
+ "actor_id": "user_1",
+ "scopes": ["read", "write"],
+ "ttl": "168h",
+ "rate_limit_policy": {
+ "quota": 1000,
+ "window": "60s"
+ }
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+## Verify with caching
+
+The first request hits the database; subsequent requests within the cache TTL are served from Redis:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}" | jq .
+```
+
+
+
+
+## Stop the stack
+
+```bash
+docker compose -f docker-compose.commercial.yaml down
+```
+
+To remove all data volumes:
+
+```bash
+docker compose -f docker-compose.commercial.yaml down -v
+```
+
+## Prerequisites
+
+You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free
+edition first.
+
+## Next steps
+
+- [Quickstart (OSS)](./index.md) — simpler setup with SQLite
+- [Architecture](../concepts/architecture.md) — admin and data plane design
+- [Caching](../concepts/caching.md) — cache behavior and consistency model
diff --git a/docs/talos/quickstart/index.md b/docs/talos/quickstart/index.md
new file mode 100644
index 0000000000..0648e2026d
--- /dev/null
+++ b/docs/talos/quickstart/index.md
@@ -0,0 +1,216 @@
+---
+title: Quickstart
+description: Issue and verify your first API key in 5 minutes
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+# Quickstart
+
+This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker
+Compose. You need Docker. Examples use the Talos CLI (with curl as an alternative).
+
+
+
+
+## Start the server
+
+```bash
+docker compose -f docker-compose.oss.yaml up --build -d
+```
+
+This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at
+http://localhost:3001). Migrations run automatically.
+
+Wait for the server to become healthy:
+
+```bash
+# Wait for the health endpoint
+for i in $(seq 1 30); do
+ if curl -sf http://localhost:8080/health/alive > /dev/null 2>&1; then
+ echo "Server is ready"
+ break
+ fi
+ sleep 1
+done
+```
+
+The server listens on `http://localhost:8080`. Check it's running:
+
+
+
+```bash
+curl -sf "$TALOS_URL/health/alive" | head -c 200
+```
+
+## Issue an API key
+
+Create an API key through the admin plane:
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "My first key" \
+ --actor quickstart-user \
+ --scopes "read:*,write:*" \
+ --ttl 168h \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+```bash
+# Issue a key and capture the response
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "My first key",
+ "actor_id": "quickstart-user",
+ "scopes": ["read:*", "write:*"],
+ "ttl": "168h"
+ }')
+
+echo "$RESPONSE" | jq .
+
+# Save the secret and key ID for later steps
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+```
+
+
+
+
+The response contains two parts:
+
+- `issued_api_key` / `id` — the key metadata (ID, name, actor, scopes, expiration).
+- `secret` — the full API key credential. This value is shown once. Store it securely.
+
+## Verify the key
+
+Send the secret to the data plane verify endpoint:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}")
+
+echo "$VERIFY_RESPONSE" | jq .
+```
+
+
+
+
+The response confirms the key is active and returns the associated metadata (actor, scopes,
+expiration).
+
+## Revoke the key
+
+Revoke the key through the admin plane using its ID:
+
+
+
+
+
+
+```bash
+talos keys revoke "$KEY_ID" --reason superseded -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+ -H "Content-Type: application/json" \
+ -d '{"reason": "Quickstart cleanup"}'
+echo ""
+echo "Key revoked"
+```
+
+
+
+
+Verify that the revoked key no longer passes verification:
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" --no-cache -e "$TALOS_URL" || true
+echo "Revocation confirmed"
+```
+
+
+
+
+```bash
+REVOKE_CHECK=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -H "Cache-Control: no-cache" \
+ -d "{\"credential\":\"$API_SECRET\"}")
+
+echo "$REVOKE_CHECK" | jq .
+
+# Verify the key is no longer active
+if echo "$REVOKE_CHECK" | jq -e '.is_active == false' > /dev/null 2>&1; then
+ echo "Revocation confirmed"
+else
+ echo "ERROR: Key should have been revoked"
+ exit 1
+fi
+```
+
+
+
+
+Revocation is immediate. Even though the key is cryptographically valid, the server checks the
+revocation list on every verification request.
+
+## Stop the server
+
+```bash
+docker compose -f docker-compose.oss.yaml down
+```
+
+To remove all data volumes:
+
+```bash
+docker compose -f docker-compose.oss.yaml down -v
+```
+
+## Next steps
+
+- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential
+ operations
+- **[Operations guide](../operate/index.md)** — install, configure, and deploy Talos in production
+- **[Architecture](../concepts/architecture.md)** — how the admin and data planes work
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..754acd5f76
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","properties":{"requests":{"items":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"actor_id":{"title":"Actor identifier (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"title":"Time-to-live for expiration (OPTIONAL)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"},"title":"Keys to import","type":"array"}},"type":"object","title":"v2BatchImportAPIKeysRequest"}}},"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..2085ed376a
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysResponse returns per-item results and summary counters.","properties":{"failure_count":{"format":"int32","type":"integer"},"results":{"items":{"description":"BatchImportResult contains the result for one key in a batch import request.","properties":{"error_code":{"default":"BATCH_IMPORT_ERROR_UNSPECIFIED","description":"BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import","enum":["BATCH_IMPORT_ERROR_UNSPECIFIED","BATCH_IMPORT_ERROR_INVALID_ARGUMENT","BATCH_IMPORT_ERROR_ALREADY_EXISTS","BATCH_IMPORT_ERROR_FAILED_PRECONDITION","BATCH_IMPORT_ERROR_INTERNAL"],"type":"string","title":"v2BatchImportErrorCode"},"error_message":{"title":"Human-readable failure reason","type":"string"},"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"},"index":{"format":"int32","title":"Zero-based index in request.requests","type":"integer"}},"type":"object","title":"v2BatchImportResult"},"type":"array"},"success_count":{"format":"int32","type":"integer"}},"type":"object","title":"v2BatchImportAPIKeysResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"Batch import completed. Check per-item results for individual status."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
new file mode 100644
index 0000000000..e99969165b
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
@@ -0,0 +1,56 @@
+---
+id: admin-plane-service-batch-import-api-keys
+title: "Batch Import API Keys"
+description: "Imports up to 1000 external API keys in one request. Returns per-item"
+sidebar_label: "Batch Import API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item
+succeeds, response is 200 OK. If all items fail, the endpoint returns a non-200 error.
+
+```http
+POST /v2/admin/importedApiKeys:batchImport
+{
+ "requests": [
+ {"raw_key": "sk_live_abc", "name": "Stripe key", "actor_id": "user_1"},
+ {"raw_key": "ghp_xyz", "name": "GitHub PAT", "actor_id": "user_2"}
+ ]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..2a18929b0d
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
new file mode 100644
index 0000000000..976062bed3
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"Imported key deleted successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
new file mode 100644
index 0000000000..d4caeadb6d
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-delete-imported-api-key
+title: "Delete Imported API Key"
+description: "Permanently deletes an imported key (hard delete). The key is removed from"
+sidebar_label: "Delete Imported API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJzdVcluIzcQ/ZUCT5JBS46SmUOfIsAGonGCKF4wB9sYl5vVao7ZZA9Z0kxDaCAfkS/MlwTFlsfyggS+5sS1tldVr7bKUCqjbdkGrwq1pNigJ8+uA0OOmBKgB9u0ITIZuKcORjVGs3sdT+CipnxtE0RqwoYMVDE0155rAoOMd5hoApeJ4Iw24Z7my8UpdVCFCClUPGiywcMoUhmahrwhM55c+2t/e3tbM7fX/vjk15OLE5huZlM0jfXTB4/mrT2lLk2399R9sqbPMkqr0FJE0bowqlBzkVk69HROcWNL+nSc3V88aMkuKa1ajNgQU0yquNo+A+f8l/m7H2bT2bv3UGOqIVQgMT4F5+zkj8vF2cnxWGllRapFrpVWHhtShRrcVFpF+rK2kYwqOK5Jq1TW1KAqtoq7Vn4mjtavVN/fyOfUBp8oyfvs6EiWMngmz7LFtnW2zOFOPyfxdftSX7j7TCWrvu/1s7jmkNZlSSlVawcPpiaq12p29NNbTL2ie7EPzlAzZs+c67IdQxWuHb8prDZKjtkOoJTBkKxViA2yKpT1/ONM6YforWdaURyMMVqXpSxTkzdojBU76Jb7anv9zMzPg7qXSdLPYNaKLTu5aGPgcLeu5r5Tj98wRsznhlLC1Rt1xrY8Z+R1ejWdHtaevrVUCtYUY4j7WRW1uJL6ftkW6kYc4jpI0wzZyk3BtSrUfzdfLvkqSCxPXfo9dnCBLiRhCYTarurDlmJOli8J5stFLpAGPa6oIc+QBo8msGCo0RtHKXebFA2UkQx5tujA2YrKrnRUgE1pbf1KNCUNG4q26uTMNTWADC58BYdMvuw0GIp2I6+pDpEPnRXi4nBPPsHow8cLQG/gNywxhuDHOh+j8JfIYK7fTFFCf+K+TZBaZxms5wD8NUArwKZCPh3CwUEGGzLaBwfw959/5Yi/u78f+0giIQ0xMLKsmTf1jml2vtPOWw0fPp6ejwcjx8j4xMYLqDMsu66CUbJ+5UjDHXJZa0jkqsPB2niv3B7TN18ulFYbimlI7GxyJEXchsQN5gbd8dzAr/C9/QWigWKfVMZev/9/Zs+ua5m+8bR1aL1AtI4us1bupSu1EW7K6qRpnipUWhW7OXGjVR0Si8R2K8FcRtf3cv1lTbFTxdWNVhuMFu8kUzKybJK9UUWFLtG/4D06242gMbx5sr0a4gO1eUnzBt1aTkrLzHucfP1Nr1VNaChmf4fHeVlSy3tiL7i/36emISWq7/8BAMEMUw==
+sidebar_class_name: "delete api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Permanently deletes an imported key (hard delete). The key is removed from the database. Use
+RevokeAPIKey for soft deletion (recommended).
+
+```http
+DELETE /v2/admin/importedApiKeys/{key_id}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
new file mode 100644
index 0000000000..e5cf6fc169
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"algorithm":{"default":"TOKEN_ALGORITHM_UNSPECIFIED","description":"- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)","enum":["TOKEN_ALGORITHM_UNSPECIFIED","TOKEN_ALGORITHM_JWT","TOKEN_ALGORITHM_MACAROON"],"title":"TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken","type":"string"},"credential":{"title":"The API key secret (issued or imported) to derive a token from","type":"string"},"custom_claims":{"type":"object"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"type":"string"}},"title":"Token derivation messages","type":"object"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
new file mode 100644
index 0000000000..4d04bb1508
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"token":{"properties":{"claims":{"type":"object"},"expire_time":{"format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token":{"type":"string"}},"title":"Token represents a short-lived derived token (JWT or Macaroon)","type":"object"}},"type":"object","title":"v2DeriveTokenResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx b/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
new file mode 100644
index 0000000000..9ca1ddf532
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-derive-token
+title: "Derive Token"
+description: "Mints a short-lived JWT or Macaroon token from an API key. Works with both"
+sidebar_label: "Derive Token"
+hide_title: true
+hide_table_of_contents: true
+api: eJztVs1y20YMfhXMnmwPJafujb1UtZ1ETm0rtjKeqelxIBISN17ubnZB2RyNZvoQfcI+SWeXkvVjJZ6m1+oicQUC2O8DPmAmCvK5k5al0SIV51KzBwRfGscdJadUwNnNEIyDc8zRGaOBzQNpGDtTAWroDfrwQE0Xbox78PAouYSR4TLT0vuaCkBdgKyscUxFsPRdGJYEBbnovfUmdUlOsgcuCSy5SnovjfZgxuEo0xYdaX6OlulMf/78uWS2mR5cXg/hcHp0iEUl9SFa+YEan7YRMj3LNEAmckcFaZaoMpFCJqg5K0fvcnkpz97+cXo1/Hjd73a7mUhac+aF3U9lJjI9j/FEIowlhwGtfiFS0QsRBwo1XZObypzuT2LUYbiVSISjrzV5/s0UjUhnIjeaSXP4idYqmUdPh198AH8mfF5SheGXdSEOS/LRVk2Mk1xW4aGgMdaKRSqGlx9OL+57v7+7vOoP35/ff7q4Hpwe99/2T09EskVsB7atz26GaeQ2UnZanFz3YM+TGndClig1FQl4OdFU7GcaXjo47x33ri4vL9JVaURX7897xy895Tgl5M4IPRX7IhGk60qkt69cYkfSO06XmYi7RLBkRQGcwEBvCRx4S7kcS2orLHeNZTNxaEuZwzO8UHsqYGzcZnX6TF8YpnRZfR72nDG8+HMf0BGgesTGg7H4taZfgEvpIVwRpAejVRO9btYGNzYk6tlJPRHzZK1CA8/PFylpGRg85Y4Y9hatZdxzZ+0Dm0XWgGstujNO7dlU97lCWcX6WliY0RfKOVj43Ni29CTThs3Ky+IAncMmPrPaYTffYqTNMZY9VOQ9TsivclxmEF4LrSMdFSJlV1MinjrGyYnUqAbosLrAKrwxCp0Vrb012rdJH7158x+6LYL38vg7cNGTlY7uWYaUZmJsXIWhQQtk6sTTHSz8EMbL1F5D2ZF15OmlmG/K7t6Wtu/voGL7ZBVqerRW0FcLAlryNsWnB77Oc/J+XCtYMtUV0W4hZj/MVm6KTdCl5p+PVveQmmlCrg3GKNUm5FgUMsRBNVh3O0+2wvzautuJ/Dfgsc6wGdXjnm52cbmo/n/n09n8mpFrvxNmDbWmJ0t5GLXknHHraAe3OPFBdF+MraCcFXFpwlCzxoeYFrkUqfjWYBWJCNxcrSbc6RNWVtHWxHpF4ddFb4nAS4la65fbpdXdQnPW+kXqsWln5Doul66BISrjgxgjlHJSdiy5WDE6X6lrhRonVIU9w7ewdKHPUKIu1GJwjGulYJUyKDmmvMkVpRA0WepJHBAJTMnJcROeuaQKkEGZR1DIpPMmadsw/Lvem+08aZsybE3PXZnER0dT8xDewdhLcQdaDgfpwVslGaRmA/xowAZ2fRqMOnBwEBmHSPnBAfz951/xxs/pr9+9nS4JOMPI4TvEpWQxapLllGmzTeDs5sP1fhvkBBk3YryAOsKyaG3Y81JPFCUwQs7LBOLK0EbbX6v5FX29QV8kYkrOt8Qedd8E1kO9VhhVQrdTodUlWE7ajXJYU5r/191X192FEDE98aFVKHUAvHZx1LcCcSumQW5jMuF7UyTuElEGOUlvxWwWlr9PTs3n4fhrTa4R6e1dIqboJI4C2bd380SUhAU5kd7OxAM1IhXHLWGdYUgmmKs6Sun2mJgnyzd6eU6Wv2u7rngBUpG0y0Q6E1WcKcLhY1jh8VGkIm7+4e04DeLZTCjUkzpquGh9hs8/obybiA==
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys.
+The derived token inherits the permissions of the parent API key.
+
+```http
+POST /v2/admin/apiKeys:derive
+{
+ "credential": "eyJhbGciOiJFZERTQSI...",
+ "ttl": "1h"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..2a18929b0d
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
new file mode 100644
index 0000000000..ea71e06032
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
new file mode 100644
index 0000000000..bbff272645
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-get-imported-api-key
+title: "Get Imported API Key"
+description: "Retrieves details about a specific imported key. Returns metadata about"
+sidebar_label: "Get Imported API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Retrieves details about a specific imported key. Returns metadata about the imported key. The
+original raw key is never returned.
+
+```http
+GET /v2/admin/importedApiKeys/{key_id}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..2be0f6afda
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..18d1a6fa3f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
new file mode 100644
index 0000000000..75d0622358
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-get-issued-api-key
+title: "Get Issued API Key"
+description: "Retrieves details about a specific issued API key including its status,"
+sidebar_label: "Get Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Retrieves details about a specific issued API key including its status, scopes, expiration, and
+usage statistics. The secret is never returned.
+
+```http
+GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
new file mode 100644
index 0000000000..fb99483d78
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"jwks":{"title":"JSON Web Key Set","type":"object"}},"type":"object","title":"v2GetJWKSResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx b/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
new file mode 100644
index 0000000000..1bfefec9bc
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
@@ -0,0 +1,43 @@
+---
+id: admin-plane-service-get-jwks
+title: "Get JWKS"
+description: "Returns the JSON Web Key Set for token verification. Provides the public"
+sidebar_label: "Get JWKS"
+hide_title: true
+hide_table_of_contents: true
+api: eJztVc1u3EYMfhViTrYx3nXdNgF0qtEmhh20WdgOfPAaNXdErcY7mlFnKG2ExQJ9iD5hn6TgaBOvnaJF0GtP8yOS30cO+WmjSkom2pZt8KpQV8Rd9Am4Jri8fv8L3NIC3tEA18RQhQgcVuShp2gra1C8JjCLobcljV5tt3DWzP2KhgSeqKQSOIweA1ze3owhEtiUOiphMQDXNkGi2FtDE0FLgJHABSypnPsqhgZM8JVddjFDwkFlHRXTqYaauU15FyIsMNGr74rpFD5cXaTDCbwNzoV1Jjb3l7fvriEx+hJjCQdXb3+E199/8/pwMvdz//DwIKHm/vzNDUz70ymWjfXTyZqcO175sPbTx/UqTR5TGK2VVqGlkc9FqQp1Jg4zh56ux1R+PScWTKVVpNQGnyipYqNOT05kMcEzeZYttq3bVXMqAHKXTE0Nyq6NAsR29BYWsrJlR6pQL19JacVDK1/C4pEMq+325Y3+7Nyf7jhe7QiqrZg/74kzSJ0xlFLVOfiUyURluwo7x/8hGxNKkrUKsUFWhbKevz19ysF6piXFEYzRuuxlmZq8wbK0goNuth92q1/A/DCG23wKmzhav/zH0rQxcFh01Zkf1JMZxoj53FBKuPzKmLE114zcpb8ts4fO08eWDFMJFGOI+9WWsLhMqrj7stPUvRDiOkgfLnMPtMi1KtS/dLLSyvoqSBbPybyPA9ygCzKmgFDbZX3cUszP5A3B2ewCVjRAgx6X1JDnpwG+YKjRl24nCFXnHJhIJXm26MDZisxgHBVZAqxfSqSkdxIhZ66pAWRwYQ0OmbwZNJQUbS9fUx0iHzvbZ2XJWnIguoK+hJ/RYAzBH+p8jNSHlfhgbuA86Tf1SF80p3WWwXoOwOsArZQ0FWJ0DEdHucyQ63x0BH/+/kfO+DP9/dwPsphpiIGRZRVc0mCbNkTecacdWw0ycYcjyE/I+Azji1Lvay0cJOuXjjQskE2tIZGrjke0w71Ge3q+s9mF0qqnmMaHPZ2cSPu2IXGDeTQ9NuJyTgw7tXrWCnuj/f/f4Wv+DjsRYPrI09ah9VL3Lrosgnk671QvUpdjKa32oimtnmb0Xqs6JBb7zUaS+BDddivXv3UUB1Xc3WvVY7S4kMe/u99qVROWFFVxt1ErGkRdjKFWhKFH12Ule6nS230ROX9zo7bbvwAzNNEW
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT
+tokens issued by this service. Keys are loaded from configuration (file://, https://, or base64://
+URIs). Follows the JWKS standard (RFC 7517).
+
+```http
+GET /v2/admin/derivedKeys/jwks.json
+```
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
new file mode 100644
index 0000000000..ad5bb8c75f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"actor_id":{"title":"Actor identifier (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"title":"Time-to-live for expiration (OPTIONAL)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"}}},"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
new file mode 100644
index 0000000000..ba7473b8df
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"}},"type":"object","title":"v2ImportAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key imported successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
new file mode 100644
index 0000000000..1d93622c48
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
@@ -0,0 +1,54 @@
+---
+id: admin-plane-service-import-api-key
+title: "Import API Key"
+description: "Imports an external API key into the system. Allows importing keys from"
+sidebar_label: "Import API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Imports an external API key into the system. Allows importing keys from legacy systems or external
+providers. The raw key is hashed and stored securely (HMAC). Imported keys support token derivation
+(JWT/Macaroon) like issued keys.
+
+```http
+POST /v2/admin/importedApiKeys
+{
+ "raw_key": "sk_live_abc123xyz",
+ "name": "Imported Stripe Key",
+ "actor_id": "user_123"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
new file mode 100644
index 0000000000..f41dd70513
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssueAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
new file mode 100644
index 0000000000..beec34909c
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"secret":{"title":"Only returned on creation","type":"string"}},"type":"object","title":"v2IssueAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key issued successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
new file mode 100644
index 0000000000..1dbaf5532f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
@@ -0,0 +1,54 @@
+---
+id: admin-plane-service-issue-api-key
+title: "Issue API Key"
+description: "Creates a new API key for a given actor. The secret is returned only once"
+sidebar_label: "Issue API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJztWtuO2zgS/ZUCn+xAdl8ykwm8L+u4nYwmlzZsJ9lBK3BoqWxxmiIVkrJjNBrYj9gv3C9ZFCnfnc5md4F9mE4DQYssFetep6i+Yxna1IjSCa1Yh/UMcocWOChcQncQwy2uYKYNcJiLBSrQS4WmDeMcwWJq0IGwYNBVRmEGWskVaJViooQClyMYtKVWFoGrDFKulHYwpWVnBC4wA8kdMXyNK0v7tGlTXWIGS+HyRNkSUzETKZRoCmGt0Mp6ZjlfIGgvOZeAX0thOD20E5Woz58/586ViRpcj8Zwtrg841kh1JmwtsKsWwo6L1F3iQJImOIFJqwDCSuNzqqU2LQsmoVIMWFRIPKaT0QWCCuLZnJx+XSz7YW2tHmTMIM8S1gECVsa4TBhn2oq52R4//kvz87zhCXq3gvLIqZLDArEGeuwLok7kFzhKMgxiUn07iB+jSsWMYNfKrTuhc5WrHPHUq0cKke/8rKUIvWczv6w5NY7ZtMcC06/lYbOcQItPYlyYtA6I9IQAHcH8RAPhtttyHAmFFqIB60pt5gBT1O0Fuhwo6UNgaLWcdNO1MccFXAp9RKzSSoyYylclFYtLEq3ikLA1LpYmBldQDywUHCX5kLNgTuQyK0DrTBRvfhqCIarOQI3GCLCOcza0Cd2BycVyBUdBvEAdrSEBpfSn1KTN9uJ2iexQEZcgdNgtHabRKCwE0WpjcPMLyzQUGx6Y3td/pKoDI2gwHb6FpWFxm8fx2cFT7nRWjW93NZxh5IsRwwpI2w1/QNTRwfGA0hzTG9tm0UH3tpT79hZR3bmIAWZbgZbw1lwOXdejJqeDq0sgsuFrd02qkpS0sJUuxziweInaGB73qaAvjhv+5+z5wlregXiweLZdv/y/Pyik02fdzpnTy8T5o07g9rdG8vvHN9Qetf2TdJbOCy8hm5VIusw2lVzdh+tF7gxfMXutwvaG5BFzAknaWFxuRe89G6Bjmfc8R3G9Wv3ka8BJ09c5/3JTcMdTqQohJuUWop0deyWIXf4higGngDC7tR7AoEYgGcAgcFxEiUqVnA9GkGhM4yCn2paYUGomTYFr8sg+YPi3ofSFCk1bVVgBtNVoqrSOoO8gDl3uOQrC42+WuhVBD2pq2wmucEI0KXtppcCiXWKBSrX9kKkuijQpILLWpYxl9qu6eyOMhYqS/krVKvAQpsVaANDzISFKU9vUWU2SpQPr1Iv0XgJvUFe9YZdaLxChUak0EMpgSwIXTnXRri8aHqT9HRRSkGKUpuAzPCZawl0sxbVfV6KFgnjZWnlyDM0tnVxfpxTXyodAmLfaX6ZzEsiqaqYoqE82lSqdfCWaGApVKaXxDp4gnWYUO7ZTyw6jpdKCV+k11FKzwcREY72G/R6O1FXOOOVdNQ21gJQ57h2ORpYcCky+r9C68WJ++OXQF2T6Ou+0JquHDWnKCyllTG0uuV2Stag17FtwvraOE4UWJvAB81GhbZ3UqFVLVwHnp1baFxAIVTlsBnB02fnYSXXlWlG8PzZT/VCxle+DhzI9GC6H+SZz86g3zp5a9KeFKR83bUkZiAyLErtUKUrX9Yb3XjQuvj55+Yps4RG77vnv1mlImr7J+kWwoqpkMLVdcP7mXXY6/7vkw/xKH4Rv4nHv0/evxsN+r34Zdy/YtGBN17j6sOGC2TCOqHmlbA5hUM1lSKFRho0tnyGTVKw7rQ1gGsQ0kHTov4VttuJGoRXPTF1Bw6ZmM2QwoaKykzMK8OnEqE0OBNfvesXwlZc1jKkNRZ7QTlOiluwOdV9ChDLixrmnW1hHdiVdVjAP//+D9gaxjeyqa4cQTxtK+qffIYuVEZowbdt1YGxx7MZcAujfm/YH7OIoaoK1rl52MYHm5uXD9YH71+8iXvs02GY7MblnoO+17K2GG8YYpfd39eBLAxmrONMhRH72tJGzIXicsANL9753sWmBAY9dcDcPjYvz8//G4Do8fKEl2JyiyeaWxzwtJcYDJYGLSqqj5sGBoEFNOZU0skbTSr1vnO0EzUkfOWjjGJDl/xLhbC4gFBK1yDKOk0top4pqIcTAPWl8Rhsvd0DW2kdAgvBIVCPidZ3yn0w1vBIzJ/UPG4Ugc+Eyh09bkp9xh22/OqJWuGnkh996RGUP4LyPw8ov8XVt8C15NZNKovZDybQI85/xPmPOP9PhfMXOtT7iUFu101zjaaH/Q/Xve44vn43Gfa7o+t3DwLq4YbZ0POC0uiFyAi/OlOlrqIg3p4I4URKUEvN3gf48GUPfr58ft5O1HsbgIvPAX8J6ZPXopy1drjMpF7aNaQ9FngwjD/Eb/qv+pOP8fjXq2H347sO+DtCD9s7vmGtg1WoQ/Y7sPd7xjjeJ8zbu347GF6/jUf9kyTdly/jN3FY6v3afffqG6xG7wf94ah/9Y3tE1o+jK0PfXUyGCYOv+4l4zXhG4sOloSEAhGF+anj/0cDIKGLyh4PeaNxd/x+dOCC3QnlJMHORrc3jj/099fIsK8PCft/G8TD/tV3Z5VRkJRqWJn9OOJ9nGgfJ9qjibYeEH0ieA8dZePOF6QwsYWi9SN9YW92DgNwGJ73o6sLtvIT0qySm69TbRLt8vziRyblU7z3R97tQXLlT9ikw388j6c6209GodzTy62lhHI4RxMOc1zI/TrFs0wEBDnYZXt/iJb+GtgdFbYHHFAa7fS0mnXV6lQBLNBaPv9BnqZM1+XohLEVVAq/lphSPqAx2uz6k9jyuaW8OPqWRuFdoMs1fWkrtaUzS+5y1mHf+FTIIkauGW6/uvW/8qKUePor2sFQeLNW9tP+dLIZR7ZZtp1Ctmsnh48a0G6pAuTcPq9h3e4Us3MfuiVc97OtlPWF5ZZkt6o/VGbo9kLN9DGWvDb1lU8YgXMxz1slGh/GKsXNMF9wxed+EoH6+2sbYgc5V5mscTOlE9WIDJWjCUWKGaarVGLH5x1NI1Tjo3APsKJnl2Phby300n9vVukqAn8lQLs218a15OH9gIdpm7ukyD8Strj1VyA+s33Bpk/hJL6wYEspHAjlNLilhpJCznaIqAVPnvgwBB+HT574nkAab8Tf1b3hgy8Co+lWIgrnYlTfc9SyYy1tBL99fD1qhkOuuON7ZxyZeu96pEHTm8QIpnS5E21x4y02dxJx677uIKZ4QGODYy/b5+R1SqKC+9ivI9qXY2+Y8MF6Lx526t/j3xz8H//moC68BJDPSsmFB9CV8R8rQkG8YQtqL14TugPaK4qfIpZT9ezcsLs7un18b+T9PS1/qdCsWOfmU8QW3AjCVfR0H7EwpLPOzR3zN8qsV4+uY5KFyGXlO8dhV7yP1m900xRL9yDtboEnd7Ao3I537ljhWygzfOlLK1VI/9cX/o6RCPzaHZNczSvfsljgSf/+BVexMPo=
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Creates a new API key for a given actor. The secret is returned only once in the response and cannot
+be retrieved later. Keys can be scoped with specific permissions and have optional expiration.
+
+```http
+POST /v2/admin/issuedApiKeys
+{
+ "name": "production-service",
+ "actor_id": "user_123",
+ "scopes": ["read", "write"],
+ "ttl": "8760h"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
new file mode 100644
index 0000000000..3a777c3e7d
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination (OPTIONAL)","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..0739f11bcd
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_keys":{"items":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"},"title":"List of imported keys","type":"array"},"next_page_token":{"title":"Token for fetching the next page (empty if no more results)","type":"string"}},"title":"ListImportedAPIKeysResponse returns paginated list of imported keys","type":"object"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
new file mode 100644
index 0000000000..25ea9577b5
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-list-imported-api-keys
+title: "List Imported API Keys"
+description: "Lists all imported keys with filtering. Returns imported keys only (not"
+sidebar_label: "List Imported API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports
+pagination and AIP-160 filter expressions.
+
+```http
+GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
new file mode 100644
index 0000000000..e8f3ff5027
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..c96bcede2f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..70db52232c
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_keys":{"items":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"type":"array"},"next_page_token":{"type":"string"}},"type":"object","title":"v2ListIssuedAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
new file mode 100644
index 0000000000..4c57b15a12
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-plane-service-list-issued-api-keys
+title: "List Issued API Keys"
+description: "Lists issued API keys with optional filtering. Supports cursor-based"
+sidebar_label: "List Issued API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter
+expressions. Returns only issued (generated) API keys; use ListImportedAPIKeys for imported keys.
+
+```http
+GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..2be0f6afda
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
new file mode 100644
index 0000000000..9894b96302
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"reason_text":{"title":"Only allowed when reason is PRIVILEGE_WITHDRAWN","type":"string"}},"type":"object","title":"AdminPlaneServiceRevokeAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
new file mode 100644
index 0000000000..f7e1bfaac2
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"API key revoked successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
new file mode 100644
index 0000000000..29a38903e4
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
@@ -0,0 +1,53 @@
+---
+id: admin-plane-service-revoke-api-key
+title: "Revoke API Key"
+description: "Immediately revokes an API key (issued or imported). Once revoked, the key"
+sidebar_label: "Revoke API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJydVu1O4zgUfZUr/xpQWtjurjSbX9uBMgQGWtryMTMZFTe5bTw4dta+KUQo0j7EPuE+ycpOKYWCEPujSpze3ON7zznXuWcp2sSIgoRWLGRRnmMqOKGswOBC36AFrqA7iOAGK/ggrC0xBW1A5IU2hOlWG/oqwWV0GgBl6GJjlXAFSoPUao4GpgilxRRm2gAvKUNFIuEOtg3jTFjQBRq/BmFBGIMLNFZMJbZjNWySu7wWuHFoxIVapUsFQVGaQlu07VjF6vr6OiMqYjXoj8aws+js8DQXaocX4hgru7P7y+HZt6s/Lr6eHR99+nh19u2s+V2dhU0hsbqPFUDMDHKrVcxCiNmwd9Hf646j/ulk2OuO+qeT497XyV7/ZDDsn0SjXsxiVXtwFrBVPVHKQtZ18APJFY7QLESCk6am7iA6xooFrOCG50hoLAu/3zPh2Cg4ZSxgiufIQnaD1USkLGAG/yqFwZSFZEoMmE0yzDkL7xlVhYu0ZISas7r+0QSjpU86rVxEohWhInfLi0IuKdj5aR3992upCuMKIIHWrZouuLsUZ7yUxMIXunF+Ohr09qKDqLfPgmfKcuU2YEOfCwqjFyJFC5ZMmVBpMPUiaoKgQbQglC1csTCtYHiwB793Pu62Y3XutCQUTDVl4LkFrlKwKGettSwzqW8bRUALNjc8GEYX0Zfe597kMhof7g+7l6cheKpaWskqBKUJuJT6tkF7lp4FDFWZs/D7m814SzovhnQPDqIvUfNo77B7+vmVVKPzQW846u2/8vcLVbIfwTOxBIwESfdg0XnOFauDpQImhHdePA/BfSWrVYduM3wgzpn4JdznsHW9eqKnPzGhtY1seGbdMl7QdV1v2uGupY2YC8XlwHnqtHHP1Me7aFtoZRtZd3Z332WKpzv16E9V3gVbJglaOyslPEC1HW5n97f3QL2UezmEl5N2DUlWHmJlzf9t80Sn6K4zbXLuPC4U/dp5JE0owjmaBoy4kP4tQZj7G56mwuFwOVhPWwfPYP5s0m3Oq9e1UBhNelrOusqzuAzjxnC/ztFaPn9nTlMkI+JU2heZVFAqvCswIUwBjdFmnVCXls/drN6UqTNXjpRpN/gLbcmPd8pYyDZPovtmrNfLc4cFzJE0fJzavTueFxLXp/Cb0+aJWVetCJhQM90M8fVS+6aCMZfaOtNyyMQ8axVovAjc0f4gvJwrPsccFYFtKm1DRJBxlUq0/uB3YoTEYOqOdy5BihkmVSIxBPfpINTcn+EBLNCIWeXWlGEOnEDqW5CcUCVVACkasXD/2kwbakmxwBRI36Cy8OHocuyH/QlPuNFabQV+6Rvo3uHeF37qj7Nm+8KCLaQgEIo00K2GwhFmQxfUgu1tTyJ4Fre34d+///EVr7a/XnvzERSA0cTJXT1xwfKLaLl3XO42gKPL49FWA7LPiT/B2Gi1b8vSrfDBCjWXGMCUU5IFj6fPDW6tyfiRvu4gYgHz302e2E57l9X1f7HVasI=
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for
+authentication. This operation is irreversible. Revoked keys are retained for audit purposes.
+
+```http
+POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
+{
+ "reason": "REVOCATION_REASON_KEY_COMPROMISE"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..05941f5ce6
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"description":"key_id is the ID of the existing API key to rotate","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..e05311863c
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"metadata for the new API key (inherits from old key if not provided)","type":"object"},"name":{"title":"name for the new API key (inherits from old key if not provided)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"scopes":{"items":{"type":"string"},"title":"scopes for the new API key (inherits from old key if not provided)","type":"array"},"update_mask":{"title":"update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"AdminPlaneServiceRotateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..ebb625d466
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"old_issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"secret":{"title":"secret is the new API key secret (only returned once, never retrievable again)","type":"string"}},"type":"object","title":"v2RotateIssuedAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key rotated successfully. New key issued, old key revoked."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
new file mode 100644
index 0000000000..dff01f94ef
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
@@ -0,0 +1,63 @@
+---
+id: admin-plane-service-rotate-issued-api-key
+title: "Rotate Issued API Key"
+description: "Generates a new secret for an issued API key. Creates a new API key with a"
+sidebar_label: "Rotate Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret,
+and immediately revokes the old key. This is the recommended way to update scopes, metadata, or
+rotate credentials.
+
+For zero-downtime rotation, use this workflow instead:
+
+1. IssueAPIKey with new credentials
+2. Deploy new secret to all services
+3. Verify new secret works everywhere
+4. RevokeAPIKey to remove the old key
+
+```http
+POST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
+{
+ "scopes": ["read"]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..2be0f6afda
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
@@ -0,0 +1 @@
+{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..5b8eea5f2d
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"type":"string"}},"type":"object","title":"AdminPlaneServiceUpdateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..18d1a6fa3f
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
new file mode 100644
index 0000000000..b3ae207fb6
--- /dev/null
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
@@ -0,0 +1,56 @@
+---
+id: admin-plane-service-update-issued-api-key
+title: "Update Issued API Key"
+description: "Updates metadata, scopes, or rate limits of an issued key without rotating"
+sidebar_label: "Update Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "patch api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use
+RotateIssuedAPIKey to change the secret.
+
+```http
+PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+{
+ "scopes": ["read"],
+ "update_mask": {"paths": ["scopes"]}
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..5630adf675
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"requests":{"items":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2VerifyAPIKeyRequest"},"type":"array"}},"type":"object","title":"v2BatchVerifyAPIKeysRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..d9a9bbcc88
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"key_id":{"type":"string"},"metadata":{"type":"object"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2VerifyAPIKeyResponse"},"type":"array"}},"type":"object","title":"v2BatchVerifyAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
new file mode 100644
index 0000000000..ed8ff75c64
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
@@ -0,0 +1,56 @@
+---
+id: data-plane-service-batch-verify-api-keys
+title: "Batch Verify API Keys"
+description: "Verifies multiple credentials in a single request. Efficiently verifies up"
+sidebar_label: "Batch Verify API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: eJztWN1uG7sRfpUBbyoHK8VxDoJCRYEqipxu4liqrDg9tQKF2p3V8phLbkiu7IVhoA/RJ+yTFEOurH/nnLboVXPhaEnOcH6/Gc4DS9EmRpROaMW67BqNyARaKCrpRCkREoMpKie4tCAUcLBCLSSCwe8VWteBQZaJRKBysoblirwqp8ppeHV6usug5IZLibIDA57kG7sg7Io+BaFSLFGlnu0fpqrkxp/JuJCVQQvckAiuMgrTzlRN1bdv33LnyqkaDa8m8HJ59pKX4iPWtjvnLsm9YvVUPUwVwJQ10tsp68INLQE8TNlaGFqfMns7k2KJMz5PXp297nQ6U/YYHT2N9Yd8/j4RQ/Hh/G+D8eQvV3EgIYqvU/XohWQR0yUaTgaPU9Zl77jjI8kVXqFZigRnb9fy9kYxqcCilcBvdVqz7gNLtHKoHP3kZSlF4vm9/MWSFx+YTXIsOP0qDd3mBFr6WqlNv4XDwu4fWWtFX044iazLeqMYbrEGbSBFI5aYgtO3qKDFVQ2ZNgV3XbC3sxcRfPgyiaDgCTdaqxMWMVeXxMM6I9SCPT4+rej5L5g4OtFcszzb1HscpGVrAm4Mr3/AYd98T3yIkEwgDKas60yFEbtvayMWQnE54oYXl7wgNnOysz9tS61sMM3Z6el/ZHtbyWdNj8ZoM0t0ivSVYsYr6SgpB+P4PO73JvHwcjYYj4fj2efLq9GgH5/Hg3cs2snhNjxP0IVLDf4uaJFPKe+4FOnJVMFB2vjyuncRv5udD8efepMu9Nc5GzxPLITyTI7xGPx1FI/p7g3inFvA+5K8cYxsPLgefjxANkdUYHCpb4/TXg4ns/Ph58ttaqUdZLpShDGQcsfn3OIxFlfx+8ve5PN4sLIBsapLpxeGl7lIwIqF4q4y2EBXiAUPU8cFiy8ng/Fl76ILsXJoFJdg0SzRNF5JK0qULY5HWY28mr2Li+EXMlMT6hCPyCekq1DgcqTk/Z0FLqW+wxT68bsxGK4WaI9avjcZzC7iT/HE8+UOQYpCOPheaccB73NeWYcptBJdFGgSwWVbK1lTxqOqCta9+XHk/jDaDp9pounwZhMzhzefguLw9p7Dj8kYPHhkd8spR4TcMC/7usav6w2nDyga+jpFKI1eihQtEOy1Lc+wCRUCC0tZuB9/VCb3wTdqUKZAa/kCNzH+z1XBVdsgT/lcri5ozkGLXAsWHYgMhJ3xxIkl/jHj0uIBjI9YSOyZE4W/JAAF67KUO2z71QNET4y9XGF3rrVErmj7FuuZSDf21pQFOk7ZvLHZ1IbHiOk7heYYpeEOZz60Z6WWIqkD+G4iKkX/BZ0Y+QMQdufkjxzBrHMjMPD+4Aqaounbk1jB8OoKCp1iBC4XdnXWQ2ewjtAEBVylUCBXDpyGOUKila0KTGFeT1VVWmeQF7DgDu94baE1UEtdR9CXukozyQ1GgC7pnHgpkFgnWKByHS/EOlkbWSZcars6ZzeUsVBRqwdCtQsstPHFf4ypsDDnyS2q1EZTNdcuh1LfofESeoO874970HqPCo1IoI9SBvzoyYU2wuXFiTdJXxelFKTonXA5pIZnri3QZW1q5Hgp2iSMl6WdI0/R2Par0w6LdsqmB6R9pwWcEsFHqirmaEBnq751jYUlGrgTKtV3xPopToVyb346FKOVEm4zbeh7JyLC1X6DyDtT9S4U8+5W6zlVQ5ejCdWX/lZovTjxYHIOtsSEzjftRnteO7RTFoWlpDKGVtfcDska9Nq3TVhfGYeysTGBD5onFTreSYVWjXBdeHNqofUKCqEqhycRvH5zGlZyXZmTCH7/5qdmIeX1Sec3Nn87ebaTnQYLLhRx2dOnV5ZG34uCouyQq5dcSA9qc8y0wd20FRYM8iSnkr1bziJ4Qr67HNVmRhFdgKuTXxc6W8pYdE/ouK3NxPuDLtuWE03z5LEEDVklJSS85IlwNbS4lE3cGUz0kvJxW6pngdcmusTt3nTvzHYPHrGlsGIupHD1drv6cfDz7Dq+it/GF/Hk52db1Y9YXz9xgVRYJ9SiEjanRKjmUiTQSiQ9Ln3ROyE4tZAZXYDFxKCDVuicQufhtztTNQqk/nBlETikIsuQEobgNBOLyvhwKA1m4j7UT2ErLhsZEpKvM1VvCd1Ibws2503gWF4geIO9LNEUwloquba2Dgv459//AWvD+AiZ68pRn6st9Ymkhws1Adpw3FZdmBjk1GBxC1eD/ngw2WisnrXxzuYT8c766PPbi7jvm48tV29m5JaDftPTLbyb/gtvtxUjotzJerBVkqC1WSVh9VLrMH+uCcZ/+7W2eoVtJvXrs3XqCOVwgSZc5riQ28nD01SEej7aZPu4W7v+FNjtZdszViqNdnpeZT1VH8rKzcbuV/M0ZXLluKvsQTMrqBTel5hQNIa2cMPaxJYvLEXl7iiDYqtAl2uac5Ta0pUldznrsiMDGhYx8sx4Pe0Y3POilLg9vbjZnlM8qfiVekiV6X1MHZq6aXUoJSEXi7xdovHuVQmuejUouOKLgO42KNGB2EHOVSqb6h6Ad/2ilCLDpE4kdkFYW1HPRMgThZa8pm+XYwHcgdR3ILlDldRRGKTQrs21cW25nqpYaH34MvGd4KfVHCXyn/7JSzTcB76HkUkexBcWbCmpnNHozd1pKMkXtkuH2vDiRS8thALvoBcvPFKRxk/ib+reIk0wAqMdd/S/f2pHIIpSG9fIjo20NPL5eHUSLqEY2Lpjz9RbL5VWGCdG4IMgAosya4fbTjYCdO2+3ihmEVuiscGxZ51TCnuKroL7lFZhhOOxBEJYefs0k7StuNjAh//PPv8Xs88GgRzeu5el5MK/6yrjh40BGm7YknD2EDh8jVhOKNK9YQ8PNLf5bOTjIy1/r9DUrHvzNWJLbgQVd/p6jFh4OXjIuMWadVm/6acnJAkdl5UH0N3i8BitKHpJgqV79uwm0JETWBRGiN0HVvhKwgy/ozEuv2Nd5mfARB0Gg9x36JKrReWRmwWe9O9fHKsoEg==
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in
+parallel. Each credential is verified independently; partial failures are returned.
+
+```http
+POST /v2/admin/apiKeys:batchVerify
+{
+ "requests": [
+ {"credential": "sk_live_abc123..."},
+ {"credential": "eyJhbGciOiJFZERTQSI..."}
+ ]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
new file mode 100644
index 0000000000..7687389d38
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","properties":{"credential":{"title":"Full API key secret or imported key (REQUIRED)","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"}},"type":"object","title":"v2SelfRevokeAPIKeyRequest"}}},"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
new file mode 100644
index 0000000000..f4b1112ea6
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success","type":"object","title":"v2SelfRevokeAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
new file mode 100644
index 0000000000..38e546e6e8
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
@@ -0,0 +1,57 @@
+---
+id: data-plane-service-self-revoke-api-key
+title: "Self-Revoke API Key"
+description: "Allows an API key holder to revoke their own key. The caller must provide"
+sidebar_label: "Self-Revoke API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJztV19v2zYQ/yqHe0oC2clSDBj0NC9xWjdt7NlJgyEKUlo6W2woUiMpJ4JhYB9in3CfZDjKsR3XbRBgD8Mwv1gij8f787vfneaYkUutLL00GmPsKGUeHAgNnUEP7qmG3KiMLHgDlmbmnsDnJC2YB83bbbjMCVKhFFkoKuehtGYmM0q0zwkmlVIrTY5SSx6EYxkzATOB0jhHzkmj2zCqytJY70A6V1H2dMwlWugMZMGblIWlNry/vgReLkQqrDEavLkn7SAVWhsPYwJHatJqTM5gz+dUJ1pYAueFJ0XO7bcTnWg2fzDsfep96L7t3l33Lt+dDjvXF2BJOKNBOmB9gsNCGUyMXStOBQct0XsiK6RuGa3qRufnz59z78tED/qjSzicHR+KUp5T7WI+Oww2JXqeaIAEU0sZaS+FSjCGBN39nZIzuhPj9IfjN+12O8GokWxMaqSG3U/9k85lr39xN+x2Rv2Lu/Pub3cn/Y+DYf9jb9RNMNGLYAlGaEqywdZehjGeCi8GSmgakZ3JlO5GK6M6g9451Rihpd8rcv4Xk9UYzzE12pP2/CjKUsnG88MvjjEzR5fmVAh+eg6mbcXDRmsTzVeALNHjeokrqaewAtbLoMIIS8vue0kueLKKNr956RVhjGc7YGrsM8zB3rD761Vv2D3dxwh9XfI5563UU1xEy9w0IZiISnmMd+To6mI06J70znrdU4y2gjVcIWrYQG9ZSA6ct1XqK0sZrGG3BKgDqV0peW9cw/DsBH48/umonegrRxlIDWPjcwgADfWyBV6YcCYCaKEFXxu8ozJi6KzgHj8rDqm31WOEpKsC45sXg/ESoHeKdM7Oeh96zdLJu87F22+oGl0NusNR9/Qb2zu8xNvtJEcrtMyOt3OFi8VK3Iy/UOqfiX+jDnDBx/6FJcPVz5DC2NuKInxsGSunUgs1EFYUF6Jgv8ZMDgH6rjTaNfV1fHT0jxJGo5pp2JKvrKYMjAZXpSk5N6nUNuIClLtF6esNOXxdcpo7d2Wns3nzk99tDHLLqn+F71vMZDLi/4mxhWD6kNq/OV6bLrWnKdnmMi+kCqekpyI8iCyTfI9Qg021i20C/LlRN9+msO8AuLTGm3E16eiQ76WYsFaE94KcE9NX6rRlOvLCV25nmDVUmh5LSpl8yVpjN6PNasXUMats9zIu24J8brjRlcbxlaXwOca4uw1jhJyY4brfdR9FUSrabhZrGnii+hcobRGh1BPzNcj7toZLoQwPOiAgl9O8VZINedcprQq8EFpMqSDtwTXetaHnIRc6U+TWJb22EpScUFqniuIwRHHl87gUwYysnNRLJihAeFDmAZTwpNM6goysnPGuy431LZ4/sqeJau9p1Pq4HLX2o/AaWIfPiFARq2GKzZcOXKmkB6m9Af9goOQkuZiFWnBwEFoIhMwdHMBff/wZPF6Zv+n7XhgHI7CGB7doyXbRsjkvbaeltRG8vz4f7TeXMDie3fFVqENYlgUKe07qqaIIxsKnebQ5QO5vIHedvs6ghxHOyLomscftI846w64QodZ1w5RMMa0GbyE8zYz1DBUbtPH/DP5fnMGXROjp0R+WSkjNUKlsGEMbhrrBGdP9Do66jTBnLotvcD4fC0dXVi0WvPx7RbbG+OY2wpmwUowZoje3iwhzEhlZjG/meE81xnjS4Kt1yYawuKoCjW+3qEX0dKKTplT678pu0i0HGqNmLIjnWIR+hlY8MGeKB4wxfIrw6dCJwtocldDTKvQPbHTy72/N4RAd
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Allows an API key holder to revoke their own key. The caller must provide the full API key secret as
+proof of possession. Supports issued API keys and imported keys. JWT and macaroon tokens cannot be
+self-revoked (they are stateless).
+
+The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
+
+```http
+POST /v2/apiKeys:selfRevoke
+{
+ "credential": "sk_live_abc123...",
+ "reason": "REVOCATION_REASON_KEY_COMPROMISE"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
new file mode 100644
index 0000000000..e6806bb713
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2VerifyAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
new file mode 100644
index 0000000000..b2d4010d3e
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
@@ -0,0 +1 @@
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"key_id":{"type":"string"},"metadata":{"type":"object"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2VerifyAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
new file mode 100644
index 0000000000..d96c487cdc
--- /dev/null
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
@@ -0,0 +1,63 @@
+---
+id: data-plane-service-verify-api-key
+title: "Verify API Key"
+description: "Verifies a single API key or derived token. Validates the credential's"
+sidebar_label: "Verify API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+Verifies a single API key or derived token. Validates the credential's signature, expiration, and
+revocation status. Works with any credential type (issued keys, imported keys, JWT, macaroon). The
+verification logic automatically detects the credential type.
+
+Returns verification result with claims and metadata. Heavily cached for optimal performance
+(typically <1ms).
+
+Cache Control (HTTP Headers):
+
+- Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
+- Cache-Control: no-store - Bypasses cache read AND write (never cached)
+- Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
+
+Use cache bypass after revoking keys when immediate verification is critical.
+
+```http
+POST /v2/admin/apiKeys:verify
+{
+ "credential": "sk_live_abc123..."
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
new file mode 100644
index 0000000000..7648813450
--- /dev/null
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -0,0 +1,44 @@
+---
+id: ory-talos-api
+title: "Ory Talos API"
+description:
+ "Ory Talos is a high-performance API key management service. It handles the full credential
+ lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
+ Macaroon), and revoking access."
+sidebar_label: "Ory Talos API"
+hide_title: true
+custom_edit_url: null
+---
+
+import ApiLogo from "@theme/ApiLogo";
+import Heading from "@theme/Heading";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import Export from "@theme/ApiExplorer/Export";
+
+
+
+
+
+Ory Talos is a high-performance API key management service. It handles the full credential
+lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
+Macaroon), and revoking access.
+
+The API is split into two planes:
+
+- **Admin Plane** — key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
+- **Data Plane** — high-performance verification (single, batch, self-revoke)
+
+### Quick Links
+
+- [**Admin Plane**](./admin-plane-service-issue-api-key) — Key lifecycle management (issue, rotate,
+ revoke, import, derive tokens, JWKS)
+- [**Data Plane**](./data-plane-service-verify-api-key) — High-performance verification (single,
+ batch, self-revoke)
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+
+```
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
new file mode 100644
index 0000000000..3693bfc24e
--- /dev/null
+++ b/docs/talos/reference/api/sidebar.ts
@@ -0,0 +1,120 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebar: SidebarsConfig = {
+ apisidebar: [
+ {
+ type: "doc",
+ id: "talos/reference/api/ory-talos-api",
+ },
+ {
+ type: "category",
+ label: "AdminPlaneService",
+ items: [
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-get-jwks",
+ label: "Get JWKS",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-revoke-api-key",
+ label: "Revoke API Key",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-derive-token",
+ label: "Derive Token",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-list-imported-api-keys",
+ label: "List Imported API Keys",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-import-api-key",
+ label: "Import API Key",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-delete-imported-api-key",
+ label: "Delete Imported API Key",
+ className: "api-method delete",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-get-imported-api-key",
+ label: "Get Imported API Key",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-batch-import-api-keys",
+ label: "Batch Import API Keys",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-list-issued-api-keys",
+ label: "List Issued API Keys",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-issue-api-key",
+ label: "Issue API Key",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-get-issued-api-key",
+ label: "Get Issued API Key",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-update-issued-api-key",
+ label: "Update Issued API Key",
+ className: "api-method patch",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/admin-plane-service-rotate-issued-api-key",
+ label: "Rotate Issued API Key",
+ className: "api-method post",
+ },
+ ],
+ },
+ {
+ type: "category",
+ label: "DataPlaneService",
+ items: [
+ {
+ type: "doc",
+ id: "talos/reference/api/data-plane-service-batch-verify-api-keys",
+ label: "Batch Verify API Keys",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/data-plane-service-self-revoke-api-key",
+ label: "Self-Revoke API Key",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "talos/reference/api/data-plane-service-verify-api-key",
+ label: "Verify API Key",
+ className: "api-method post",
+ },
+ ],
+ },
+ ],
+};
+
+export default sidebar.apisidebar;
diff --git a/docs/talos/reference/cli/.gitkeep b/docs/talos/reference/cli/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
new file mode 100644
index 0000000000..8944c885dc
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
@@ -0,0 +1,60 @@
+---
+id: talos-jwk-generate-ecdsa
+title: talos jwk generate ecdsa
+description: talos jwk generate ecdsa
+---
+
+
+
+## talos jwk generate ecdsa
+
+Generate an ECDSA key pair
+
+### Synopsis
+
+Generate an ECDSA key pair using the specified elliptic curve. Key size is determined by the curve:
+P-256 (256-bit), P-384 (384-bit), P-521 (521-bit). Default curve: P-256.
+
+```
+talos jwk generate ecdsa [flags]
+```
+
+### Examples
+
+```
+ # Generate P-256 key (default)
+ talos jwk generate ecdsa -o ecdsa-key.json
+
+ # Generate P-384 key with custom key ID
+ talos jwk generate ecdsa --curve P-384 --kid prod-ec-key -o ecdsa-p384.json
+
+ # Generate P-521 key
+ talos jwk generate ecdsa --curve P-521 -o ecdsa-p521.json
+```
+
+### Options
+
+```
+ --curve string Elliptic curve (P-256, P-384, P-521) (default "P-256")
+ -h, --help help for ecdsa
+ --jwks Output as JWKS (JSON Web Key Set)
+ --kid string Key ID (JWK Thumbprint used if not provided)
+ -o, --output string Output file (writes to stdout if not specified)
+ --public-only Output public key only
+ --use string Key usage: 'sig' for signing, 'enc' for encryption (default: sig)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-eddsa.md b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
new file mode 100644
index 0000000000..6567b04937
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
@@ -0,0 +1,61 @@
+---
+id: talos-jwk-generate-eddsa
+title: talos jwk generate eddsa
+description: talos jwk generate eddsa
+---
+
+
+
+## talos jwk generate eddsa
+
+Generate an EdDSA (Ed25519) key pair
+
+### Synopsis
+
+Generate an EdDSA key pair using the Ed25519 curve. Ed25519 uses a fixed 256-bit key size.
+
+```
+talos jwk generate eddsa [flags]
+```
+
+### Examples
+
+```
+ # Generate with auto-generated key ID
+ talos jwk generate eddsa -o signing-key.json
+
+ # Generate with custom key ID
+ talos jwk generate eddsa --kid prod-key-1 -o signing-key.json
+
+ # Generate public key only
+ talos jwk generate eddsa --public-only -o public-key.json
+
+ # Generate as JWKS format
+ talos jwk generate eddsa --jwks -o keys.jwks.json
+```
+
+### Options
+
+```
+ -h, --help help for eddsa
+ --jwks Output as JWKS (JSON Web Key Set)
+ --kid string Key ID (JWK Thumbprint used if not provided)
+ -o, --output string Output file (writes to stdout if not specified)
+ --public-only Output public key only
+ --use string Key usage: 'sig' for signing, 'enc' for encryption (default: sig)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-hmac.md b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
new file mode 100644
index 0000000000..3d01d7f0bd
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
@@ -0,0 +1,59 @@
+---
+id: talos-jwk-generate-hmac
+title: talos jwk generate hmac
+description: talos jwk generate hmac
+---
+
+
+
+## talos jwk generate hmac
+
+Generate an HMAC secret key
+
+### Synopsis
+
+Generate a symmetric HMAC secret key. Default size is 512 bits. Minimum is 256 bits. Algorithm is
+determined by key size: 256→HS256, 384→HS384, ≥512→HS512.
+
+```
+talos jwk generate hmac [flags]
+```
+
+### Examples
+
+```
+ # Generate 512-bit HMAC secret (default)
+ talos jwk generate hmac -o hmac-secret.json
+
+ # Generate 256-bit HMAC secret
+ talos jwk generate hmac --bits 256 -o hmac-256.json
+
+ # Generate with custom key ID
+ talos jwk generate hmac --kid signing-secret-1 -o hmac-key.json
+```
+
+### Options
+
+```
+ --bits int Key size in bits (default 512, minimum 256) (default 512)
+ -h, --help help for hmac
+ --jwks Output as JWKS (JSON Web Key Set)
+ --kid string Key ID (JWK Thumbprint used if not provided)
+ -o, --output string Output file (writes to stdout if not specified)
+ --use string Key usage: 'sig' for signing, 'enc' for encryption (default: sig)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-rsa.md b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
new file mode 100644
index 0000000000..8057e5fc51
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
@@ -0,0 +1,63 @@
+---
+id: talos-jwk-generate-rsa
+title: talos jwk generate rsa
+description: talos jwk generate rsa
+---
+
+
+
+## talos jwk generate rsa
+
+Generate an RSA key pair
+
+### Synopsis
+
+Generate an RSA key pair with the specified key size. Default is 2048 bits. Minimum is 2048 bits.
+
+```
+talos jwk generate rsa [flags]
+```
+
+### Examples
+
+```
+ # Generate RSA key (default: 2048 bits)
+ talos jwk generate rsa -o rsa-key.json
+
+ # Generate 4096-bit RSA key
+ talos jwk generate rsa --bits 4096 -o rsa-4096.json
+
+ # Generate with custom algorithm
+ talos jwk generate rsa --alg RS512 -o rsa-rs512.json
+
+ # Generate public key only
+ talos jwk generate rsa --public-only -o rsa-public.json
+```
+
+### Options
+
+```
+ --alg string Algorithm override (e.g. RS384, RS512, PS256)
+ --bits int Key size in bits (minimum 2048) (default 2048)
+ -h, --help help for rsa
+ --jwks Output as JWKS (JSON Web Key Set)
+ --kid string Key ID (JWK Thumbprint used if not provided)
+ -o, --output string Output file (writes to stdout if not specified)
+ --public-only Output public key only
+ --use string Key usage: 'sig' for signing, 'enc' for encryption (default: sig)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate.md b/docs/talos/reference/cli/talos-jwk-generate.md
new file mode 100644
index 0000000000..eb6aded4f9
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-generate.md
@@ -0,0 +1,40 @@
+---
+id: talos-jwk-generate
+title: talos jwk generate
+description: talos jwk generate
+---
+
+
+
+## talos jwk generate
+
+Generate a new JWK key
+
+### Synopsis
+
+Generate a new cryptographic key in JWK format for signing or encryption.
+
+### Options
+
+```
+ -h, --help help for generate
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk](talos-jwk) Generate JSON Web Keys (JWK/JWKS)
+- [talos jwk generate ecdsa](talos-jwk-generate-ecdsa) - Generate an ECDSA key pair
+- [talos jwk generate eddsa](talos-jwk-generate-eddsa) - Generate an EdDSA (Ed25519) key pair
+- [talos jwk generate hmac](talos-jwk-generate-hmac) - Generate an HMAC secret key
+- [talos jwk generate rsa](talos-jwk-generate-rsa) - Generate an RSA key pair
diff --git a/docs/talos/reference/cli/talos-jwk-get.md b/docs/talos/reference/cli/talos-jwk-get.md
new file mode 100644
index 0000000000..a50284863d
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk-get.md
@@ -0,0 +1,36 @@
+---
+id: talos-jwk-get
+title: talos jwk get
+description: talos jwk get
+---
+
+
+
+## talos jwk get
+
+Fetch the server's JSON Web Key Set (JWKS)
+
+```
+talos jwk get [flags]
+```
+
+### Options
+
+```
+ -h, --help help for get
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos jwk](talos-jwk) Generate JSON Web Keys (JWK/JWKS)
diff --git a/docs/talos/reference/cli/talos-jwk.md b/docs/talos/reference/cli/talos-jwk.md
new file mode 100644
index 0000000000..b95eedf0c8
--- /dev/null
+++ b/docs/talos/reference/cli/talos-jwk.md
@@ -0,0 +1,39 @@
+---
+id: talos-jwk
+title: talos jwk
+description: talos jwk
+---
+
+
+
+## talos jwk
+
+Generate JSON Web Keys (JWK/JWKS)
+
+### Synopsis
+
+Generate cryptographic keys in JSON Web Key (JWK) format. Supports EdDSA (Ed25519), ECDSA (P-256,
+P-384, P-521), RSA, and HMAC algorithms.
+
+### Options
+
+```
+ -h, --help help for jwk
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos](talos) High-performance multi-network API key service
+- [talos jwk generate](talos-jwk-generate) - Generate a new JWK key
+- [talos jwk get](talos-jwk-get) - Fetch the server's JSON Web Key Set (JWKS)
diff --git a/docs/talos/reference/cli/talos-keys-batch-verify.md b/docs/talos/reference/cli/talos-keys-batch-verify.md
new file mode 100644
index 0000000000..39d99b1585
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-batch-verify.md
@@ -0,0 +1,39 @@
+---
+id: talos-keys-batch-verify
+title: talos keys batch-verify
+description: talos keys batch-verify
+---
+
+
+
+## talos keys batch-verify
+
+Verify multiple credentials in a single request
+
+```
+talos keys batch-verify [credentials...] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for batch-verify
+ --no-cache Bypass verification cache (sends Cache-Control: no-cache header)
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-derive-token.md b/docs/talos/reference/cli/talos-keys-derive-token.md
new file mode 100644
index 0000000000..7e1eae3fce
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-derive-token.md
@@ -0,0 +1,46 @@
+---
+id: talos-keys-derive-token
+title: talos keys derive-token
+description: talos keys derive-token
+---
+
+
+
+## talos keys derive-token
+
+Derive a new derived token from an existing API key
+
+### Synopsis
+
+Derives a new short-lived derived token from an existing opaque API key. The output will be a JWT or
+Macaroon token.
+
+```
+talos keys derive-token [api-key-token] [flags]
+```
+
+### Options
+
+```
+ --algorithm string Algorithm for derived token (jwt or macaroon) (default "jwt")
+ --claims string Custom claims as JSON (e.g., '{"user_ip":"192.168.1.1","request_id":"abc123"}'). Reserved claims like iss, sub, exp cannot be overridden.
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for derive-token
+ -q, --quiet Be quiet with output printing.
+ --ttl string Token time-to-live duration (default "1h")
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-batch-import.md b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
new file mode 100644
index 0000000000..866d5ea91f
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
@@ -0,0 +1,44 @@
+---
+id: talos-keys-imported-batch-import
+title: talos keys imported batch-import
+description: talos keys imported batch-import
+---
+
+
+
+## talos keys imported batch-import
+
+Batch import API keys from a JSON file
+
+### Synopsis
+
+Batch import API keys from a JSON file. Each request is limited to 1000 keys; the server rejects
+batches that exceed this limit.
+
+```
+talos keys imported batch-import --file keys.json [flags]
+```
+
+### Options
+
+```
+ --file string Path to JSON file with key array, or '-' for stdin
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for batch-import
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-delete.md b/docs/talos/reference/cli/talos-keys-imported-delete.md
new file mode 100644
index 0000000000..96bb8fd95a
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-delete.md
@@ -0,0 +1,38 @@
+---
+id: talos-keys-imported-delete
+title: talos keys imported delete
+description: talos keys imported delete
+---
+
+
+
+## talos keys imported delete
+
+Permanently delete an imported API key
+
+```
+talos keys imported delete [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for delete
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-get.md b/docs/talos/reference/cli/talos-keys-imported-get.md
new file mode 100644
index 0000000000..fb3e848021
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-get.md
@@ -0,0 +1,38 @@
+---
+id: talos-keys-imported-get
+title: talos keys imported get
+description: talos keys imported get
+---
+
+
+
+## talos keys imported get
+
+Get details of an imported API key
+
+```
+talos keys imported get [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for get
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-import.md b/docs/talos/reference/cli/talos-keys-imported-import.md
new file mode 100644
index 0000000000..adff651e8d
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-import.md
@@ -0,0 +1,46 @@
+---
+id: talos-keys-imported-import
+title: talos keys imported import
+description: talos keys imported import
+---
+
+
+
+## talos keys imported import
+
+Import an external API key
+
+```
+talos keys imported import [name] [flags]
+```
+
+### Options
+
+```
+ --actor string Actor ID (required)
+ --allowed-cidrs string Comma-separated CIDR ranges for IP restriction (e.g., '10.0.0.0/8,192.168.0.0/16')
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for import
+ --metadata string JSON metadata for the imported key
+ -q, --quiet Be quiet with output printing.
+ --rate-limit-quota int Maximum requests allowed per window (0 = no limit)
+ --rate-limit-window string Rate limit window duration (e.g., 60s, 5m)
+ --raw-key string The raw key string to import (required)
+ --scopes string Comma-separated list of scopes
+ --ttl string Time-to-live duration (e.g., '24h', '8760h')
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-list.md b/docs/talos/reference/cli/talos-keys-imported-list.md
new file mode 100644
index 0000000000..405adc8ff0
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-list.md
@@ -0,0 +1,42 @@
+---
+id: talos-keys-imported-list
+title: talos keys imported list
+description: talos keys imported list
+---
+
+
+
+## talos keys imported list
+
+List imported API keys
+
+```
+talos keys imported list [flags]
+```
+
+### Options
+
+```
+ --actor string Filter by actor ID
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for list
+ --page-size int32 Number of items per page (default: 50, max: 1000)
+ --page-token string Cursor token for pagination
+ -q, --quiet Be quiet with output printing.
+ --status string Filter by status (KEY_STATUS_ACTIVE, KEY_STATUS_REVOKED, KEY_STATUS_EXPIRED)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-revoke.md b/docs/talos/reference/cli/talos-keys-imported-revoke.md
new file mode 100644
index 0000000000..5eb5cc2cd7
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported-revoke.md
@@ -0,0 +1,40 @@
+---
+id: talos-keys-imported-revoke
+title: talos keys imported revoke
+description: talos keys imported revoke
+---
+
+
+
+## talos keys imported revoke
+
+Revoke an imported API key
+
+```
+talos keys imported revoke [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for revoke
+ -q, --quiet Be quiet with output printing.
+ --reason string Reason for revocation (key_compromise, affiliation_changed, superseded, privilege_withdrawn)
+ --reason-text string Human-readable reason text
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys imported](talos-keys-imported) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported.md b/docs/talos/reference/cli/talos-keys-imported.md
new file mode 100644
index 0000000000..a33dd97b8c
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-imported.md
@@ -0,0 +1,45 @@
+---
+id: talos-keys-imported
+title: talos keys imported
+description: talos keys imported
+---
+
+
+
+## talos keys imported
+
+Manage imported API keys
+
+### Synopsis
+
+Import, list, get, revoke, and delete externally-created API keys.
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for imported
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
+- [talos keys imported batch-import](talos-keys-imported-batch-import) - Batch import API keys from
+ a JSON file
+- [talos keys imported delete](talos-keys-imported-delete) - Permanently delete an imported API key
+- [talos keys imported get](talos-keys-imported-get) - Get details of an imported API key
+- [talos keys imported import](talos-keys-imported-import) - Import an external API key
+- [talos keys imported list](talos-keys-imported-list) - List imported API keys
+- [talos keys imported revoke](talos-keys-imported-revoke) - Revoke an imported API key
diff --git a/docs/talos/reference/cli/talos-keys-issue.md b/docs/talos/reference/cli/talos-keys-issue.md
new file mode 100644
index 0000000000..bfc1dc6195
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issue.md
@@ -0,0 +1,45 @@
+---
+id: talos-keys-issue
+title: talos keys issue
+description: talos keys issue
+---
+
+
+
+## talos keys issue
+
+Issue a new API key
+
+```
+talos keys issue [name] [flags]
+```
+
+### Options
+
+```
+ --actor string Actor ID (required)
+ --allowed-cidrs string Comma-separated CIDR ranges for IP restriction (e.g., '10.0.0.0/8,192.168.0.0/16')
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for issue
+ --metadata string JSON metadata for the API key
+ -q, --quiet Be quiet with output printing.
+ --rate-limit-quota int Maximum requests allowed per window (0 = no limit)
+ --rate-limit-window string Rate limit window duration (e.g., 60s, 5m)
+ --scopes string Comma-separated list of scopes
+ --ttl duration Time-to-live duration (e.g., '24h', '168h') (default 24h0m0s)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-get.md b/docs/talos/reference/cli/talos-keys-issued-get.md
new file mode 100644
index 0000000000..287a81acea
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued-get.md
@@ -0,0 +1,38 @@
+---
+id: talos-keys-issued-get
+title: talos keys issued get
+description: talos keys issued get
+---
+
+
+
+## talos keys issued get
+
+Get details of an issued API key
+
+```
+talos keys issued get [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for get
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys issued](talos-keys-issued) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-issue.md b/docs/talos/reference/cli/talos-keys-issued-issue.md
new file mode 100644
index 0000000000..f1821c17c7
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued-issue.md
@@ -0,0 +1,45 @@
+---
+id: talos-keys-issued-issue
+title: talos keys issued issue
+description: talos keys issued issue
+---
+
+
+
+## talos keys issued issue
+
+Issue a new API key
+
+```
+talos keys issued issue [name] [flags]
+```
+
+### Options
+
+```
+ --actor string Actor ID (required)
+ --allowed-cidrs string Comma-separated CIDR ranges for IP restriction (e.g., '10.0.0.0/8,192.168.0.0/16')
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for issue
+ --metadata string JSON metadata for the API key
+ -q, --quiet Be quiet with output printing.
+ --rate-limit-quota int Maximum requests allowed per window (0 = no limit)
+ --rate-limit-window string Rate limit window duration (e.g., 60s, 5m)
+ --scopes string Comma-separated list of scopes
+ --ttl duration Time-to-live duration (e.g., '24h', '168h') (default 24h0m0s)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys issued](talos-keys-issued) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-list.md b/docs/talos/reference/cli/talos-keys-issued-list.md
new file mode 100644
index 0000000000..137f0398d0
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued-list.md
@@ -0,0 +1,42 @@
+---
+id: talos-keys-issued-list
+title: talos keys issued list
+description: talos keys issued list
+---
+
+
+
+## talos keys issued list
+
+List issued API keys
+
+```
+talos keys issued list [flags]
+```
+
+### Options
+
+```
+ --actor string Filter by actor ID
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for list
+ --page-size int32 Number of items per page (default: 50, max: 1000)
+ --page-token string Cursor token for pagination
+ -q, --quiet Be quiet with output printing.
+ --status string Filter by status (KEY_STATUS_ACTIVE, KEY_STATUS_REVOKED, KEY_STATUS_EXPIRED)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys issued](talos-keys-issued) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-rotate.md b/docs/talos/reference/cli/talos-keys-issued-rotate.md
new file mode 100644
index 0000000000..df8c7783f8
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued-rotate.md
@@ -0,0 +1,41 @@
+---
+id: talos-keys-issued-rotate
+title: talos keys issued rotate
+description: talos keys issued rotate
+---
+
+
+
+## talos keys issued rotate
+
+Rotate an issued API key (revokes old key, creates new one)
+
+```
+talos keys issued rotate [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for rotate
+ --metadata string JSON metadata for the rotated key
+ --name string New name for the rotated API key
+ -q, --quiet Be quiet with output printing.
+ --scopes string Comma-separated list of scopes for the rotated key
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys issued](talos-keys-issued) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-update.md b/docs/talos/reference/cli/talos-keys-issued-update.md
new file mode 100644
index 0000000000..4b49862269
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued-update.md
@@ -0,0 +1,44 @@
+---
+id: talos-keys-issued-update
+title: talos keys issued update
+description: talos keys issued update
+---
+
+
+
+## talos keys issued update
+
+Update an issued API key
+
+```
+talos keys issued update [key-id] [flags]
+```
+
+### Options
+
+```
+ --allowed-cidrs string Comma-separated CIDR ranges for IP restriction (empty string removes restrictions)
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for update
+ --metadata string JSON metadata for the API key
+ --name string New name for the API key
+ -q, --quiet Be quiet with output printing.
+ --rate-limit-quota int Maximum requests allowed per window (0 = no limit)
+ --rate-limit-window string Rate limit window duration (e.g., 60s, 5m)
+ --scopes string Comma-separated list of scopes
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys issued](talos-keys-issued) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued.md b/docs/talos/reference/cli/talos-keys-issued.md
new file mode 100644
index 0000000000..b0ada7b6cc
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-issued.md
@@ -0,0 +1,44 @@
+---
+id: talos-keys-issued
+title: talos keys issued
+description: talos keys issued
+---
+
+
+
+## talos keys issued
+
+Manage issued API keys
+
+### Synopsis
+
+Get, list, update, and rotate issued API keys.
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for issued
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
+- [talos keys issued get](talos-keys-issued-get) - Get details of an issued API key
+- [talos keys issued issue](talos-keys-issued-issue) - Issue a new API key
+- [talos keys issued list](talos-keys-issued-list) - List issued API keys
+- [talos keys issued rotate](talos-keys-issued-rotate) - Rotate an issued API key (revokes old key,
+ creates new one)
+- [talos keys issued update](talos-keys-issued-update) - Update an issued API key
diff --git a/docs/talos/reference/cli/talos-keys-revoke.md b/docs/talos/reference/cli/talos-keys-revoke.md
new file mode 100644
index 0000000000..89d87a6f5b
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-revoke.md
@@ -0,0 +1,39 @@
+---
+id: talos-keys-revoke
+title: talos keys revoke
+description: talos keys revoke
+---
+
+
+
+## talos keys revoke
+
+Revoke an API key
+
+```
+talos keys revoke [key-id] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for revoke
+ -q, --quiet Be quiet with output printing.
+ --reason string Reason for revocation
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-self-revoke.md b/docs/talos/reference/cli/talos-keys-self-revoke.md
new file mode 100644
index 0000000000..a8cc6f8f3f
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-self-revoke.md
@@ -0,0 +1,44 @@
+---
+id: talos-keys-self-revoke
+title: talos keys self-revoke
+description: talos keys self-revoke
+---
+
+
+
+## talos keys self-revoke
+
+Revoke an API key using the credential itself as proof
+
+### Synopsis
+
+Self-revokes an API key by presenting the full credential as proof of ownership. Does not require
+admin access.
+
+```
+talos keys self-revoke [credential] [flags]
+```
+
+### Options
+
+```
+ -h, --help help for self-revoke
+ --reason string Reason for revocation
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -q, --quiet Be quiet with output printing.
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-verify.md b/docs/talos/reference/cli/talos-keys-verify.md
new file mode 100644
index 0000000000..3b1e7940ee
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys-verify.md
@@ -0,0 +1,44 @@
+---
+id: talos-keys-verify
+title: talos keys verify
+description: talos keys verify
+---
+
+
+
+## talos keys verify
+
+Verify a credential (API key or token)
+
+### Synopsis
+
+Verifies a credential against the server. Checks if the credential is active, not expired, and not
+revoked.
+
+```
+talos keys verify [credential] [flags]
+```
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for verify
+ --no-cache Bypass verification cache (sends Cache-Control: no-cache header)
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos keys](talos-keys) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys.md b/docs/talos/reference/cli/talos-keys.md
new file mode 100644
index 0000000000..d1524a60e4
--- /dev/null
+++ b/docs/talos/reference/cli/talos-keys.md
@@ -0,0 +1,49 @@
+---
+id: talos-keys
+title: talos keys
+description: talos keys
+---
+
+
+
+## talos keys
+
+Manage API keys
+
+### Synopsis
+
+Create, list, get, revoke, and rotate API keys.
+
+### Options
+
+```
+ --format string Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "table")
+ -h, --help help for keys
+ -q, --quiet Be quiet with output printing.
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos](talos) High-performance multi-network API key service
+- [talos keys batch-verify](talos-keys-batch-verify) - Verify multiple credentials in a single
+ request
+- [talos keys derive-token](talos-keys-derive-token) - Derive a new derived token from an existing
+ API key
+- [talos keys imported](talos-keys-imported) - Manage imported API keys
+- [talos keys issue](talos-keys-issue) - Issue a new API key
+- [talos keys issued](talos-keys-issued) - Manage issued API keys
+- [talos keys revoke](talos-keys-revoke) - Revoke an API key
+- [talos keys self-revoke](talos-keys-self-revoke) - Revoke an API key using the credential itself
+ as proof
+- [talos keys verify](talos-keys-verify) - Verify a credential (API key or token)
diff --git a/docs/talos/reference/cli/talos-migrate-down.md b/docs/talos/reference/cli/talos-migrate-down.md
new file mode 100644
index 0000000000..8d61c5ac20
--- /dev/null
+++ b/docs/talos/reference/cli/talos-migrate-down.md
@@ -0,0 +1,55 @@
+---
+id: talos-migrate-down
+title: talos migrate down
+description: talos migrate down
+---
+
+
+
+## talos migrate down
+
+Rollback migrations
+
+### Synopsis
+
+Roll back the last N migrations (default: 1).
+
+This is useful for reverting recent migrations in development. In production, use this carefully and
+ensure you have backups.
+
+```
+talos migrate down [flags]
+```
+
+### Examples
+
+```
+ # Roll back last migration
+ talos migrate down
+
+ # Roll back last 3 migrations
+ talos migrate down --steps 3
+```
+
+### Options
+
+```
+ --database string database DSN (overrides DB_DSN)
+ -h, --help help for down
+ --steps int number of migrations to roll back (default 1)
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos migrate](talos-migrate) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-force.md b/docs/talos/reference/cli/talos-migrate-force.md
new file mode 100644
index 0000000000..ab28e7bce8
--- /dev/null
+++ b/docs/talos/reference/cli/talos-migrate-force.md
@@ -0,0 +1,57 @@
+---
+id: talos-migrate-force
+title: talos migrate force
+description: talos migrate force
+---
+
+
+
+## talos migrate force
+
+Force set migration version (use with caution)
+
+### Synopsis
+
+Force the migration version to a specific value.
+
+This is useful when:
+
+- A migration failed and left the database in a dirty state
+- You need to manually fix the database state
+- You want to mark a migration as applied without running it
+
+WARNING: This command should be used carefully as it can lead to inconsistent database state if used
+incorrectly.
+
+```
+talos migrate force VERSION [flags]
+```
+
+### Examples
+
+```
+ # Mark database as clean at version 5
+ talos migrate force 5
+```
+
+### Options
+
+```
+ --database string database DSN (overrides DB_DSN)
+ -h, --help help for force
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos migrate](talos-migrate) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-status.md b/docs/talos/reference/cli/talos-migrate-status.md
new file mode 100644
index 0000000000..7ba3945f05
--- /dev/null
+++ b/docs/talos/reference/cli/talos-migrate-status.md
@@ -0,0 +1,47 @@
+---
+id: talos-migrate-status
+title: talos migrate status
+description: talos migrate status
+---
+
+
+
+## talos migrate status
+
+Show migration status
+
+### Synopsis
+
+Display the current database migration status.
+
+Shows:
+
+- Current migration version
+- Whether the database is in a dirty state
+- Database connection info
+
+```
+talos migrate status [flags]
+```
+
+### Options
+
+```
+ --database string database DSN (overrides DB_DSN)
+ -h, --help help for status
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos migrate](talos-migrate) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-up.md b/docs/talos/reference/cli/talos-migrate-up.md
new file mode 100644
index 0000000000..83be0a7908
--- /dev/null
+++ b/docs/talos/reference/cli/talos-migrate-up.md
@@ -0,0 +1,63 @@
+---
+id: talos-migrate-up
+title: talos migrate up
+description: talos migrate up
+---
+
+
+
+## talos migrate up
+
+Run all pending migrations
+
+### Synopsis
+
+Apply all pending migrations to the database.
+
+The database connection string can be provided via:
+
+- DB_DSN environment variable
+- --database flag (overrides DB_DSN)
+
+```
+talos migrate up [flags]
+```
+
+### Examples
+
+```
+ # SQLite
+ talos migrate up --database "sqlite3://./data/talos.db"
+
+ # PostgreSQL (commercial)
+ export DB_DSN="postgres://user:pass@localhost:5432/talos?sslmode=disable"
+ talos migrate up
+
+ # MySQL (commercial)
+ talos migrate up --database "mysql://user:pass@tcp(localhost:3306)/talos"
+
+ # CockroachDB (commercial)
+ talos migrate up --database "cockroach://user:pass@localhost:5432/talos?sslmode=disable"
+```
+
+### Options
+
+```
+ --database string database DSN (overrides DB_DSN)
+ -h, --help help for up
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos migrate](talos-migrate) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate.md b/docs/talos/reference/cli/talos-migrate.md
new file mode 100644
index 0000000000..9173facd32
--- /dev/null
+++ b/docs/talos/reference/cli/talos-migrate.md
@@ -0,0 +1,40 @@
+---
+id: talos-migrate
+title: talos migrate
+description: talos migrate
+---
+
+
+
+## talos migrate
+
+Database migration tools
+
+### Synopsis
+
+Run database migrations for the API Key service
+
+### Options
+
+```
+ -h, --help help for migrate
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos](talos) High-performance multi-network API key service
+- [talos migrate down](talos-migrate-down) - Rollback migrations
+- [talos migrate force](talos-migrate-force) - Force set migration version (use with caution)
+- [talos migrate status](talos-migrate-status) - Show migration status
+- [talos migrate up](talos-migrate-up) - Run all pending migrations
diff --git a/docs/talos/reference/cli/talos-proxy.md b/docs/talos/reference/cli/talos-proxy.md
new file mode 100644
index 0000000000..16f81709b2
--- /dev/null
+++ b/docs/talos/reference/cli/talos-proxy.md
@@ -0,0 +1,40 @@
+---
+id: talos-proxy
+title: talos proxy
+description: talos proxy
+---
+
+
+
+## talos proxy
+
+Start the edge proxy (commercial edition only)
+
+### Synopsis
+
+The proxy command is only available in the commercial edition.
+
+```
+talos proxy [flags]
+```
+
+### Options
+
+```
+ -h, --help help for proxy
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos](talos) High-performance multi-network API key service
diff --git a/docs/talos/reference/cli/talos-serve-admin.md b/docs/talos/reference/cli/talos-serve-admin.md
new file mode 100644
index 0000000000..4172673b4a
--- /dev/null
+++ b/docs/talos/reference/cli/talos-serve-admin.md
@@ -0,0 +1,57 @@
+---
+id: talos-serve-admin
+title: talos serve admin
+description: talos serve admin
+---
+
+
+
+## talos serve admin
+
+Start the admin plane server (management only)
+
+### Synopsis
+
+Starts the admin plane server for API key and network management.
+
+This mode runs only the management endpoints for administrative operations. It's designed for
+internal tools, CI/CD, and administrative access.
+
+Features:
+
+- Full read/write database access
+- API key creation, rotation, revocation
+- Network management
+- Signing key management
+- Typically behind admin firewall
+
+```
+talos serve admin [flags]
+```
+
+### Examples
+
+```
+ talos serve admin
+```
+
+### Options
+
+```
+ -h, --help help for admin
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos serve](talos-serve) Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/cli/talos-serve-check.md b/docs/talos/reference/cli/talos-serve-check.md
new file mode 100644
index 0000000000..0bb2183449
--- /dev/null
+++ b/docs/talos/reference/cli/talos-serve-check.md
@@ -0,0 +1,51 @@
+---
+id: talos-serve-check
+title: talos serve check
+description: talos serve check
+---
+
+
+
+## talos serve check
+
+Start the data plane server (verification only)
+
+### Synopsis
+
+Starts the data plane server for API key and token verification.
+
+This mode runs only the verification endpoints with caching for optimal read performance. It's
+designed for edge deployments and high-throughput verification workloads.
+
+Cache configuration is read from the config file (cache.type, cache.ttl, etc.)
+
+```
+talos serve check [flags]
+```
+
+### Examples
+
+```
+ talos serve check
+```
+
+### Options
+
+```
+ -h, --help help for check
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos serve](talos-serve) Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/cli/talos-serve.md b/docs/talos/reference/cli/talos-serve.md
new file mode 100644
index 0000000000..81dc4a1ec1
--- /dev/null
+++ b/docs/talos/reference/cli/talos-serve.md
@@ -0,0 +1,55 @@
+---
+id: talos-serve
+title: talos serve
+description: talos serve
+---
+
+
+
+## talos serve
+
+Start the Ory Talos server (all-in-one mode)
+
+### Synopsis
+
+Starts the HTTP server for the API key service in all-in-one mode.
+
+This mode runs both admin plane (management) and data plane (verification) in a single process.
+
+For production deployments with high-throughput verification workloads, consider using:
+
+- 'serve check' for data plane only (verification with caching)
+- 'serve admin' for admin plane only (management operations)
+
+```
+talos serve [flags]
+```
+
+### Examples
+
+```
+ talos serve
+```
+
+### Options
+
+```
+ -h, --help help for serve
+```
+
+### Options inherited from parent commands
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+```
+
+### See also
+
+- [talos](talos) High-performance multi-network API key service
+- [talos serve admin](talos-serve-admin) - Start the admin plane server (management only)
+- [talos serve check](talos-serve-check) - Start the data plane server (verification only)
diff --git a/docs/talos/reference/cli/talos.md b/docs/talos/reference/cli/talos.md
new file mode 100644
index 0000000000..68f8b42fb8
--- /dev/null
+++ b/docs/talos/reference/cli/talos.md
@@ -0,0 +1,38 @@
+---
+id: talos
+title: talos
+description: talos
+---
+
+
+
+## talos
+
+High-performance multi-network API key service
+
+### Synopsis
+
+API Key Service is a high-performance, multi-network service for managing API keys with support for
+JWT tokens, JWKS, and various cryptographic algorithms.
+
+It provides both admin plane and data plane APIs for comprehensive key management.
+
+### Options
+
+```
+ --config string config file (default is $HOME/.talos.yaml or ./config.yaml)
+ -e, --endpoint string HTTP server base URL including scheme, e.g. http://host:port (for client commands) (default "http://localhost:4420")
+ -h, --help help for talos
+```
+
+### See also
+
+- [talos jwk](talos-jwk) - Generate JSON Web Keys (JWK/JWKS)
+- [talos keys](talos-keys) - Manage API keys
+- [talos migrate](talos-migrate) - Database migration tools
+- [talos proxy](talos-proxy) - Start the edge proxy (commercial edition only)
+- [talos serve](talos-serve) - Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/config.md b/docs/talos/reference/config.md
new file mode 100644
index 0000000000..20b6fca4f2
--- /dev/null
+++ b/docs/talos/reference/config.md
@@ -0,0 +1,192 @@
+---
+title: Configuration reference
+description: Auto-generated configuration reference from JSON Schema
+---
+
+# Configuration reference
+
+This page is auto-generated from the
+[configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
+
+Required top-level keys: `credentials`, `secrets`
+
+## Environment variables
+
+Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and
+converts dot-separated config paths to uppercase with underscores:
+
+```
+TALOS__
+```
+
+Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port`
+becomes `TALOS_SERVE_HTTP_PORT`.
+
+### Array values
+
+For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed
+variables:
+
+```bash
+# Comma-separated
+export TALOS_SECRETS_HMAC_RETIRED="old-secret-1,old-secret-2"
+
+# Or indexed
+export TALOS_SECRETS_HMAC_RETIRED_0="old-secret-1"
+export TALOS_SECRETS_HMAC_RETIRED_1="old-secret-2"
+```
+
+### Precedence
+
+Configuration sources are applied in this order (highest priority first):
+
+1. Environment variables
+2. Configuration file (`--config` flag)
+3. Default values
+
+Environment variables always override file-based configuration.
+
+### Required variables
+
+At minimum, these must be set (via env var or config file):
+
+| Variable | Description |
+| ------------------------------- | ------------------------------------------------- |
+| `TALOS_SECRETS_DEFAULT_CURRENT` | Default secret for HMAC operations (min 32 chars) |
+| `TALOS_CREDENTIALS_ISSUER` | Token issuer (`iss` claim) for derived tokens |
+
+## `cache` Commercial
+
+Cache configuration.
+
+| Key | Type | Default | Env Var | Description |
+| -------------------------------- | ------------------------- | -------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `cache.memory.max_size` | integer | `104857600` | `TALOS_CACHE_MEMORY_MAX_SIZE` | Maximum memory usage in bytes. (restart required, Commercial) |
+| `cache.memory.num_counters` | integer | `10000` | `TALOS_CACHE_MEMORY_NUM_COUNTERS` | Number of counters for frequency estimation. (restart required, Commercial) |
+| `cache.redis.addrs` | string[] | `["localhost:6379"]` | `TALOS_CACHE_REDIS_ADDRS` | Redis server addresses (supports cluster/sentinel). (restart required, Commercial) |
+| `cache.redis.conn_max_idle_time` | string | `5m` | `TALOS_CACHE_REDIS_CONN_MAX_IDLE_TIME` | Maximum duration a connection may be idle before being closed. (restart required, Commercial) |
+| `cache.redis.conn_max_lifetime` | string | `30m` | `TALOS_CACHE_REDIS_CONN_MAX_LIFETIME` | Maximum duration a connection may be reused. (restart required, Commercial) |
+| `cache.redis.db` | integer | `0` | `TALOS_CACHE_REDIS_DB` | Redis database number. (restart required, Commercial) |
+| `cache.redis.min_idle_conns` | integer | `2` | `TALOS_CACHE_REDIS_MIN_IDLE_CONNS` | Minimum number of idle connections kept open. (restart required, Commercial) |
+| `cache.redis.password` | string | — | `TALOS_CACHE_REDIS_PASSWORD` | Redis password. (restart required, Commercial) |
+| `cache.redis.pool_size` | integer | `100` | `TALOS_CACHE_REDIS_POOL_SIZE` | Connection pool size (Commercial) |
+| `cache.redis.timeout` | string | `3s` | `TALOS_CACHE_REDIS_TIMEOUT` | Redis operation timeout (duration string) (Commercial) |
+| `cache.redis.tls.enabled` | boolean | `false` | `TALOS_CACHE_REDIS_TLS_ENABLED` | Enable TLS using the system certificate pool. (restart required, Commercial) |
+| `cache.ttl` | string | `5m` | `TALOS_CACHE_TTL` | Default cache TTL (duration string). (Commercial) |
+| `cache.type` | `memory`, `redis`, `noop` | `noop` | `TALOS_CACHE_TYPE` | Cache implementation type. (restart required, Commercial) |
+
+## `credentials`
+
+Credential configuration for API keys and derived tokens (JWT, macaroon).
+
+| Key | Type | Default | Env Var | Description |
+| ---------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials.api_keys.default_ttl` | string | — | `TALOS_CREDENTIALS_API_KEYS_DEFAULT_TTL` | Default API key TTL (duration string). |
+| `credentials.api_keys.max_ttl` | string | `8760h` | `TALOS_CREDENTIALS_API_KEYS_MAX_TTL` | Maximum age for API keys with timestamps. |
+| `credentials.api_keys.prefix.current` | string | `ory_ak` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_CURRENT` | Current prefix used for new API key generation. |
+| `credentials.api_keys.prefix.public_current` | string | — | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_CURRENT` | Current prefix used for new PUBLIC API key generation. |
+| `credentials.api_keys.prefix.public_retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_RETIRED` | Retired public prefixes accepted during verification for migration purposes. |
+| `credentials.api_keys.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_RETIRED` | Retired prefixes accepted during verification for migration purposes. |
+| `credentials.clock_skew` | string | `5m` | `TALOS_CREDENTIALS_CLOCK_SKEW` | Maximum clock skew tolerance for timestamp and token validation. |
+| `credentials.derived_tokens.default_ttl` | string | `1h` | `TALOS_CREDENTIALS_DERIVED_TOKENS_DEFAULT_TTL` | Default derived token TTL applied to both JWT and macaroon tokens when no explicit TTL is provided in the request (duration string) |
+| `credentials.derived_tokens.jwt.algorithm` | `EdDSA`, `RS256` | `EdDSA` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_ALGORITHM` | Token signing algorithm. |
+| `credentials.derived_tokens.jwt.signing_keys.urls` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEYS_URLS` | List of JWKS resources. |
+| `credentials.derived_tokens.macaroon.prefix.current` | string | `mc` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_CURRENT` | Current prefix used for new macaroon token generation. |
+| `credentials.derived_tokens.macaroon.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_RETIRED` | Retired prefixes accepted during macaroon verification for rotation purposes. |
+| `credentials.issuer` | string | — | `TALOS_CREDENTIALS_ISSUER` | Token issuer (iss claim) for derived tokens. (min 1 chars) |
+| `credentials.issuer_retired` | string[] | `[]` | `TALOS_CREDENTIALS_ISSUER_RETIRED` | Retired issuer URLs accepted during token verification. |
+
+## `db` (restart required)
+
+Database configuration.
+
+| Key | Type | Default | Env Var | Description |
+| -------- | ------ | ------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `db.dsn` | string | — | `TALOS_DB_DSN` | Database connection string with scheme and optional query parameters. (restart required, min 1 chars) |
+
+## `last_used` (restart required)
+
+Configuration for batched last_used_at timestamp updates.
+
+| Key | Type | Default | Env Var | Description |
+| -------------------------- | ------- | ------- | -------------------------------- | ------------------------------------------------------------------------------- |
+| `last_used.flush_interval` | string | `30s` | `TALOS_LAST_USED_FLUSH_INTERVAL` | Maximum time between batch flushes (Go duration string, e.g. (restart required) |
+| `last_used.flush_size` | integer | `100` | `TALOS_LAST_USED_FLUSH_SIZE` | Number of updates per shard that triggers a batch flush. (restart required) |
+| `last_used.num_workers` | integer | `4` | `TALOS_LAST_USED_NUM_WORKERS` | Number of goroutines processing last-used batches. (restart required) |
+| `last_used.queue_size` | integer | `10000` | `TALOS_LAST_USED_QUEUE_SIZE` | Buffer size for the async last-used update queue. (restart required) |
+
+## `log` (restart required)
+
+Logging configuration.
+
+| Key | Type | Default | Env Var | Description |
+| ------------ | -------------------------------- | ------- | ------------------ | ------------------------------ |
+| `log.format` | `json`, `text` | `json` | `TALOS_LOG_FORMAT` | Log format. (restart required) |
+| `log.level` | `debug`, `info`, `warn`, `error` | `info` | `TALOS_LOG_LEVEL` | Log level. (restart required) |
+
+## `multitenancy` Commercial (restart required)
+
+Multi-tenancy configuration.
+
+| Key | Type | Default | Env Var | Description |
+| ----------------------- | -------- | ------- | ----------------------------- | ------------------------------------------------------------- |
+| `multitenancy.enabled` | boolean | `false` | `TALOS_MULTITENANCY_ENABLED` | Enable multi-tenancy support. (restart required, Commercial) |
+| `multitenancy.networks` | object[] | `[]` | `TALOS_MULTITENANCY_NETWORKS` | Network routing configuration. (restart required, Commercial) |
+
+## `rate_limit` Commercial
+
+Rate limit enforcement for API keys with a RateLimitPolicy.
+
+| Key | Type | Default | Env Var | Description |
+| -------------------- | ----------------- | -------- | -------------------------- | ----------------------------------------------- |
+| `rate_limit.backend` | `memory`, `redis` | `memory` | `TALOS_RATE_LIMIT_BACKEND` | Counter backend. (restart required, Commercial) |
+| `rate_limit.enabled` | boolean | `false` | `TALOS_RATE_LIMIT_ENABLED` | Enable rate limit enforcement. (Commercial) |
+
+## `secrets`
+
+Centralized secrets management.
+
+| Key | Type | Default | Env Var | Description |
+| ---------------------------- | -------- | ------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `secrets.default.current` | string | — | `TALOS_SECRETS_DEFAULT_CURRENT` | Current default secret for all components without specific overrides (min 32 chars) |
+| `secrets.default.retired` | string[] | `[]` | `TALOS_SECRETS_DEFAULT_RETIRED` | Retired default secrets that remain valid for verification during rotation |
+| `secrets.hmac.current` | string | — | `TALOS_SECRETS_HMAC_CURRENT` | Current HMAC secret for new key generation and checksum verification (min 32 chars) |
+| `secrets.hmac.retired` | string[] | `[]` | `TALOS_SECRETS_HMAC_RETIRED` | Retired HMAC secrets that remain valid for verification during rotation |
+| `secrets.pagination.current` | string | — | `TALOS_SECRETS_PAGINATION_CURRENT` | Secret used to sign and encrypt pagination tokens. (min 32 chars) |
+| `secrets.pagination.retired` | string[] | `[]` | `TALOS_SECRETS_PAGINATION_RETIRED` | List of retired pagination secrets that should remain valid for decoding legacy page tokens during secret rotation. |
+
+## `serve`
+
+Server configuration for HTTP and metrics endpoints.
+
+| Key | Type | Default | Env Var | Description |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serve.http.client_ip_source` | `CLIENT_IP_SOURCE_UNSPECIFIED`, `CLIENT_IP_SOURCE_REMOTE_ADDR`, `CLIENT_IP_SOURCE_CF_CONNECTING_IP`, `CLIENT_IP_SOURCE_X_FORWARDED_FOR`, `CLIENT_IP_SOURCE_X_REAL_IP`, `CLIENT_IP_SOURCE_TRUE_CLIENT_IP` | `CLIENT_IP_SOURCE_UNSPECIFIED` | `TALOS_SERVE_HTTP_CLIENT_IP_SOURCE` | Determines which HTTP header or connection property is used to resolve the client IP for IP restriction checks. Must match your infrastructure topology. Default (unspecified) uses the TCP remote address. Hot-reloadable: read dynamically per request. |
+| `serve.http.cors.allow_credentials` | boolean | `false` | `TALOS_SERVE_HTTP_CORS_ALLOW_CREDENTIALS` | Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates. |
+| `serve.http.cors.allowed_headers` | string[] | `["Authorization","Content-Type"]` | `TALOS_SERVE_HTTP_CORS_ALLOWED_HEADERS` | A list of non simple headers the client is allowed to use with cross-domain requests. (min 1 chars) |
+| `serve.http.cors.allowed_methods` | string[] | `["GET","POST","PUT","PATCH","DELETE"]` | `TALOS_SERVE_HTTP_CORS_ALLOWED_METHODS` | A list of methods the client is allowed to use with cross-domain requests. |
+| `serve.http.cors.allowed_origins` | string[] | `["*"]` | `TALOS_SERVE_HTTP_CORS_ALLOWED_ORIGINS` | A list of origins a cross-domain request can be executed from. |
+| `serve.http.cors.debug` | boolean | `false` | `TALOS_SERVE_HTTP_CORS_DEBUG` | Set to true to debug server side CORS issues. |
+| `serve.http.cors.enabled` | boolean | `false` | `TALOS_SERVE_HTTP_CORS_ENABLED` | If set to true, CORS will be enabled and preflight-requests (OPTION) will be answered. |
+| `serve.http.cors.exposed_headers` | string[] | `["Content-Type"]` | `TALOS_SERVE_HTTP_CORS_EXPOSED_HEADERS` | Indicates which headers are safe to expose to the API of a CORS API specification (min 1 chars) |
+| `serve.http.cors.max_age` | number | `0` | `TALOS_SERVE_HTTP_CORS_MAX_AGE` | Indicates how long (in seconds) the results of a preflight request can be cached. |
+| `serve.http.host` | string | `0.0.0.0` | `TALOS_SERVE_HTTP_HOST` | The host (interface) that the endpoint listens on. (restart required) |
+| `serve.http.port` | integer | `4420` | `TALOS_SERVE_HTTP_PORT` | The port that the endpoint listens on. (restart required) |
+| `serve.http.request_log.exclude_health_endpoints` | boolean | `false` | `TALOS_SERVE_HTTP_REQUEST_LOG_EXCLUDE_HEALTH_ENDPOINTS` | Exclude /health/alive and /health/ready endpoints from request logs |
+| `serve.http.trust_forwarded_host` | boolean | `false` | `TALOS_SERVE_HTTP_TRUST_FORWARDED_HOST` | Trust the X-Forwarded-Host header for tenant routing. (restart required) |
+| `serve.metrics.host` | string | `0.0.0.0` | `TALOS_SERVE_METRICS_HOST` | The host (interface) that the metrics endpoint listens on. (restart required) |
+| `serve.metrics.port` | integer | `4422` | `TALOS_SERVE_METRICS_PORT` | The port that the metrics endpoint listens on. (restart required) |
+
+## `tracing` (restart required)
+
+OpenTelemetry tracing configuration.
+
+| Key | Type | Default | Env Var | Description |
+| ------------------------- | ------- | ------------- | ------------------------------- | ------------------------------------------------------------------ |
+| `tracing.enabled` | boolean | `false` | `TALOS_TRACING_ENABLED` | Enable tracing. (restart required) |
+| `tracing.endpoint` | string | — | `TALOS_TRACING_ENDPOINT` | Trace collector endpoint. (restart required) |
+| `tracing.environment` | string | `development` | `TALOS_TRACING_ENVIRONMENT` | Deployment environment tag in trace attributes. (restart required) |
+| `tracing.exporter` | `otlp` | — | `TALOS_TRACING_EXPORTER` | Trace exporter type. (restart required) |
+| `tracing.sample_rate` | number | `0.001` | `TALOS_TRACING_SAMPLE_RATE` | Sampling rate (0.0 to 1.0). (restart required) |
+| `tracing.service_name` | string | `talos` | `TALOS_TRACING_SERVICE_NAME` | Service name reported to OpenTelemetry. (restart required) |
+| `tracing.service_version` | string | `0.0.0` | `TALOS_TRACING_SERVICE_VERSION` | Service version reported to OpenTelemetry. (restart required) |
diff --git a/docs/talos/reference/error-codes.md b/docs/talos/reference/error-codes.md
new file mode 100644
index 0000000000..532765e224
--- /dev/null
+++ b/docs/talos/reference/error-codes.md
@@ -0,0 +1,101 @@
+---
+title: Error codes
+description: HTTP and gRPC error codes returned by the Talos API
+---
+
+
+
+
+# Error codes
+
+Talos returns structured error responses following the [herodot](https://github.com/ory/herodot)
+error format. Every error response includes an `id`, HTTP status code, status text, and a
+human-readable message.
+
+## Error response format
+
+```json
+{
+ "error": {
+ "code": 400,
+ "status": "Bad Request",
+ "message": "The API key format is invalid.",
+ "reason": "Additional context about the error"
+ }
+}
+```
+
+## Application errors
+
+| Error ID | HTTP | gRPC | Description |
+| ----------------------------- | ---- | --------------------- | -------------------------------------------------------------------------- |
+| `bad_request` | 400 | `INVALID_ARGUMENT` | The request was malformed or contained invalid parameters |
+| `credential_required` | 400 | `INVALID_ARGUMENT` | A credential is required. |
+| `derived_token_not_revocable` | 400 | `INVALID_ARGUMENT` | Derived tokens cannot be revoked. |
+| `invalid_api_key_format` | 400 | `INVALID_ARGUMENT` | The API key format is invalid. |
+| `invalid_token_type` | 400 | `INVALID_ARGUMENT` | The token type is invalid. |
+| `unknown_credential` | 400 | `INVALID_ARGUMENT` | The credential type is not recognized. |
+| `api_key_expired` | 401 | `UNAUTHENTICATED` | The API key has expired. |
+| `api_key_revoked` | 401 | `UNAUTHENTICATED` | The API key has been revoked. |
+| `parent_key_invalid` | 401 | `UNAUTHENTICATED` | Parent key validation failed. |
+| `signature_invalid` | 401 | `UNAUTHENTICATED` | Signature verification failed. |
+| `unauthorized` | 401 | `UNAUTHENTICATED` | The request could not be authorized |
+| `forbidden` | 403 | `PERMISSION_DENIED` | The requested action was forbidden |
+| `ip_not_allowed` | 403 | `PERMISSION_DENIED` | The request IP is not allowed for this API key. |
+| `payment_required` | 403 | `PERMISSION_DENIED` | The feature is not available and requires payment. |
+| `api_key_not_found` | 404 | `NOT_FOUND` | The API key was not found. |
+| `not_found` | 404 | `NOT_FOUND` | The requested resource could not be found |
+| `api_key_exists` | 409 | `ALREADY_EXISTS` | An API key with this identifier already exists. |
+| `conflict` | 409 | `ALREADY_EXISTS` | The resource could not be created due to a conflict |
+| `failed_precondition` | 409 | `FAILED_PRECONDITION` | The operation cannot be completed due to a failed precondition. |
+| `too_many_requests` | 429 | `RESOURCE_EXHAUSTED` | The request was throttled due to resource exhaustion. |
+| `internal_server_error` | 500 | `INTERNAL` | An internal server error occurred, please contact the system administrator |
+| `service_unavailable` | 503 | `UNAVAILABLE` | The service is temporarily unavailable. |
+| `gateway_timeout` | 504 | `DEADLINE_EXCEEDED` | The operation timed out. |
+
+## Standard HTTP errors
+
+| Error ID | HTTP | Description |
+| -------------------------------- | ---- | ------------------------ |
+| Standard `bad_request` | 400 | Generic validation error |
+| Standard `unauthorized` | 401 | Authentication required |
+| Standard `forbidden` | 403 | Insufficient permissions |
+| Standard `not_found` | 404 | Resource not found |
+| Standard `conflict` | 409 | Resource conflict |
+| Standard `internal_server_error` | 500 | Unexpected server error |
+
+## Verification error codes
+
+The `VerifyAPIKey` response includes an `error_code` enum when verification fails:
+
+| Code | Meaning |
+| -------------------------------------- | -------------------------------------------------- |
+| `VERIFICATION_ERROR_UNSPECIFIED` | No error (key is valid) |
+| `VERIFICATION_ERROR_INVALID_FORMAT` | Credential format is invalid |
+| `VERIFICATION_ERROR_EXPIRED` | Credential has expired |
+| `VERIFICATION_ERROR_REVOKED` | Credential has been revoked |
+| `VERIFICATION_ERROR_NOT_FOUND` | Credential not found in database |
+| `VERIFICATION_ERROR_SIGNATURE_INVALID` | Cryptographic signature verification failed |
+| `VERIFICATION_ERROR_INTERNAL` | Internal server error during verification |
+| `VERIFICATION_ERROR_IP_NOT_ALLOWED` | Request IP is not in the key's allowed CIDR ranges |
+| `VERIFICATION_ERROR_RATE_LIMITED` | Rate limit quota exhausted (commercial-only) |
+
+## Batch import error codes
+
+The `BatchImportAPIKeys` response includes per-item error codes:
+
+| Code | Meaning |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `BATCH_IMPORT_ERROR_UNSPECIFIED` | No error (import succeeded) |
+| `BATCH_IMPORT_ERROR_INVALID_ARGUMENT` | The key data is malformed or missing required fields |
+| `BATCH_IMPORT_ERROR_ALREADY_EXISTS` | A key with this identifier already exists |
+| `BATCH_IMPORT_ERROR_FAILED_PRECONDITION` | State conflict prevents the import |
+| `BATCH_IMPORT_ERROR_INTERNAL` | Server error during import |
+
+## Error handling recommendations
+
+- **4xx errors**: Fix the request and retry. Do not retry without changes.
+- **409 Conflict**: Check if the resource already exists or is in an incompatible state.
+- **5xx errors**: Retry with exponential backoff and jitter.
+- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After`
+ header value if present.
diff --git a/docs/talos/reference/events.md b/docs/talos/reference/events.md
new file mode 100644
index 0000000000..26b5d8751d
--- /dev/null
+++ b/docs/talos/reference/events.md
@@ -0,0 +1,79 @@
+---
+title: Audit events
+description: Structured audit events emitted by Talos via OpenTelemetry
+---
+
+
+
+
+# Audit events
+
+Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle
+operations. Events are attached to the active OTEL span and forwarded to any configured OTEL
+collector. They are never persisted locally.
+
+Each event carries a set of structured attributes that provide context about the operation, the
+actor, and the affected resource.
+
+## Event types
+
+| Constant | Event Name | Description |
+| ----------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
+| `EventAPIKeyCreated` | `APIKeyCreated` | EventAPIKeyCreated is emitted when an API key is created (issued or imported). |
+| Use the KeyType attribute to distinguish between the two origins. |
+| `EventAPIKeyUpdated` | `APIKeyUpdated` | EventAPIKeyUpdated is emitted when an API key's metadata is updated. |
+| `EventAPIKeyRevoked` | `APIKeyRevoked` | EventAPIKeyRevoked is emitted when an API key is revoked. |
+| `EventAPIKeyRotated` | `APIKeyRotated` | EventAPIKeyRotated is emitted when an API key is rotated. |
+| `EventAPIKeyVerified` | `APIKeyVerified` | EventAPIKeyVerified is emitted when an API key is successfully verified. |
+| `EventAPIKeyVerificationFailed` | `APIKeyVerificationFailed` | EventAPIKeyVerificationFailed is emitted when an API key verification fails. |
+| `EventAPIKeyImportFailed` | `APIKeyImportFailed` | EventAPIKeyImportFailed is emitted when an API key import fails. |
+| `EventTokenDerived` | `TokenDerived` | EventTokenDerived is emitted when a session token is derived from an API key. |
+| `EventAPIKeyDeleted` | `APIKeyDeleted` | EventAPIKeyDeleted is emitted when an issued API key is permanently deleted. |
+| `EventImportedAPIKeyDeleted` | `ImportedAPIKeyDeleted` | EventImportedAPIKeyDeleted is emitted when an imported API key is permanently deleted. |
+
+## Event attributes
+
+Each event carries the following OTEL span event attributes:
+
+| OTEL Key | Struct Field | Type | Required | Description |
+| -------------- | ------------ | ----------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `` | `NetworkID` | uuid.UUID | Required | AttrNetworkID uses the shared semconv NID key so the analytics pipeline can route by project. |
+| `APIKeyID` | `KeyID` | string | Optional | Key identification (present for key-related events) |
+| `APIKeyPrefix` | `Prefix` | string | Optional | |
+| `KeyType` | `KeyType` | string | Optional | Key origin (present for created/rotated events) |
+| `Operation` | `Operation` | string | Optional | Operation context |
+| `Reason` | `Reason` | string | Optional | Failure reason or additional context |
+| `ActorID` | `ActorID` | string | Optional | Actor information (who performed the operation) |
+| `Expiry` | `Expiry` | \*time.Time | Optional | Key properties (present for create/rotate/update events) |
+| `Visibility` | `Visibility` | string | Optional | "public" or "secret" |
+| `metadata.` | `Metadata` | map[string]string | Optional | Additional context (varies by event type) |
+
+## Dynamic metadata attributes
+
+The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys
+are prefixed with `metadata.` in OTEL attributes. For example, a metadata entry
+`{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with value `jwt`.
+
+Metadata is optional and varies by event type. Common metadata keys include:
+
+- `token_type` — Type of derived token (e.g., `jwt`, `macaroon`)
+- `previous_key_id` — ID of the key being replaced during rotation
+- `import_source` — Origin of an imported API key
+
+## Emitting events
+
+Events are constructed using the fluent builder pattern:
+
+```go
+emitter := events.NewOTELEmitter()
+events.New(events.EventAPIKeyCreated).
+ WithNetworkID(networkID).
+ WithKeyType("issued").
+ WithKeyID(keyID).
+ WithPrefix("talos").
+ WithActor(actorID).
+ Emit(ctx, emitter)
+```
+
+Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently
+dropped.
diff --git a/docs/talos/reference/index.md b/docs/talos/reference/index.md
new file mode 100644
index 0000000000..a99ce7691e
--- /dev/null
+++ b/docs/talos/reference/index.md
@@ -0,0 +1,21 @@
+---
+title: Reference
+description: API, configuration, and technical reference
+---
+
+# Reference
+
+Technical reference documentation for Ory Talos.
+
+## API
+
+- [API reference](api/ory-talos-api.info.mdx) — auto-generated from the OpenAPI specification
+
+## Configuration
+
+- [Configuration reference](config.md) — all configuration keys with types and defaults
+
+## Technical details
+
+- [Error codes](error-codes.md) — HTTP and gRPC error codes returned by the API
+- [Token format](token-format.md) — API key and session token structure
diff --git a/docs/talos/reference/token-format.md b/docs/talos/reference/token-format.md
new file mode 100644
index 0000000000..7788928497
--- /dev/null
+++ b/docs/talos/reference/token-format.md
@@ -0,0 +1,107 @@
+---
+title: Token format reference
+description: API key and derived token structure
+---
+
+# Token format
+
+Talos uses structured token formats that encode metadata for efficient routing and verification.
+
+## API key format
+
+Generated API keys follow a versioned format:
+
+```
+_v1__
+```
+
+Example:
+
+```
+prod_v1_5Z7Hn9K3mPqRtVwXyBcDeFgHiJkLmNoPqRsTuVwXyZ_AbC3XyZ789e
+```
+
+### Components
+
+| Component | Length | Description |
+| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `prefix` | 1-8 chars | User-defined label (e.g., `prod`, `dev`, `test`). Set via `credentials.api_keys.prefix.current` in config. |
+| `v1` | 2 chars | Format version identifier |
+| `identifier` | ~32 chars | Base58-encoded timestamp and UUID v4 |
+| `checksum` | 10-11 chars | HMAC-SHA256 truncated to 64 bits, Base58-encoded |
+
+### Identifier encoding
+
+The identifier is a Base58 encoding of `timestamp:uuid`:
+
+- **Timestamp**: Unix epoch seconds (int64). Embedded at key creation time.
+- **UUID**: UUID v4 (36 chars with hyphens). Used as the `key_id` for database lookup.
+
+Base58 encoding uses the Bitcoin alphabet
+(`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually ambiguous
+characters (`0`, `O`, `I`, `l`).
+
+### Checksum verification
+
+The checksum is computed over the payload `prefix_v1_identifier_`:
+
+1. Compute HMAC-SHA256 using the current HMAC secret
+2. Truncate to 64 bits
+3. Base58-encode the result
+
+During verification, all configured secrets (current + retired) are tried in order. This supports
+secret rotation without invalidating existing keys.
+
+### Credential routing
+
+When a credential is submitted for verification, Talos identifies the credential type by format:
+
+| Format match | Credential type | Lookup method |
+| ----------------------------------- | ----------------- | ---------------------------------------- |
+| `_v1__` | Generated API key | UUID extracted from identifier |
+| JWT format (`eyJ...`) | Derived JWT | Claims extracted during verification |
+| Macaroon prefix (`_v1_...`) | Derived macaroon | Identifier extracted during verification |
+| None of the above | Imported key | SHA-512/256 hash with tenant scope |
+
+## Imported key format
+
+Imported keys have no format requirements. Any string credential can be imported. Talos stores a
+tenant-scoped hash:
+
+```
+SHA-512/256(network_id + 0x00 + raw_key)
+```
+
+The null byte separator prevents ambiguity between network ID and key content.
+
+## Derived token formats
+
+### JWT
+
+Derived tokens produced as JWTs follow the standard JWT format:
+
+```
+eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature
+```
+
+Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm
+is determined by the `alg` field in the JWK (EdDSA or RS256).
+
+### Macaroon
+
+Macaroon tokens use a configurable prefix:
+
+```
+_v1_
+```
+
+The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`).
+The data section contains the macaroon identifier and signature.
+
+## ID formats
+
+| Context | Format | Length | Example |
+| ------------------ | ----------------------- | --------- | -------------------------------------- |
+| Database storage | UUID v4 string | 36 chars | `550e8400-e29b-41d4-a716-446655440000` |
+| API key identifier | Base58-encoded | ~32 chars | `5Z7Hn9K3mPqRtVwXyBcDeFg` |
+| Imported key hash | Hex-encoded SHA-512/256 | 64 chars | `a1b2c3d4...` |
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 295267dca0..cf5410e324 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -231,6 +231,7 @@ const config: Config = {
],
"@docusaurus/theme-search-algolia",
"docusaurus-theme-redoc",
+ "docusaurus-theme-openapi-docs",
],
headTags: [],
}
diff --git a/package-lock.json b/package-lock.json
index e1720c1264..5c0d06a3c6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -30,6 +30,8 @@
"classnames": "2.5.1",
"clsx": "2.1.0",
"debug": "4.3.4",
+ "docusaurus-plugin-openapi-docs": "4.7.1",
+ "docusaurus-theme-openapi-docs": "4.7.1",
"file-loader": "6.2.0",
"json-loader": "0.5.7",
"json-schema-faker": "0.5.8",
@@ -4383,6 +4385,13 @@
"integrity": "sha512-5Aap/GaRupgNx/feGBwLLTVv8OQFfv3pq2lPRzPg9R+IOBnDgghTGW7l7EuVXOvg5cc/xSAlRW8rBrjIC3Nvqw==",
"license": "MIT"
},
+ "node_modules/@faker-js/faker": {
+ "version": "5.5.3",
+ "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-5.5.3.tgz",
+ "integrity": "sha512-R11tGE6yIFwqpaIqcfkcg7AICXzFg14+5h5v0TfF/9+RMDL6jhzCy/pxHVOfbALGdtVYdt6JdR21tuxEgl34dw==",
+ "deprecated": "Please update to a newer version.",
+ "license": "MIT"
+ },
"node_modules/@hapi/hoek": {
"version": "9.3.0",
"license": "BSD-3-Clause"
@@ -4394,6 +4403,17 @@
"@hapi/hoek": "^9.0.0"
}
},
+ "node_modules/@hookform/error-message": {
+ "version": "2.0.1",
+ "resolved": "https://registry.npmjs.org/@hookform/error-message/-/error-message-2.0.1.tgz",
+ "integrity": "sha512-U410sAr92xgxT1idlu9WWOVjndxLdgPUHEB8Schr27C9eh7/xUnITWpCMF93s+lGiG++D4JnbSnrb5A21AdSNg==",
+ "license": "MIT",
+ "peerDependencies": {
+ "react": ">=16.8.0",
+ "react-dom": ">=16.8.0",
+ "react-hook-form": "^7.0.0"
+ }
+ },
"node_modules/@iconify-json/tabler": {
"version": "1.2.19",
"resolved": "https://registry.npmjs.org/@iconify-json/tabler/-/tabler-1.2.19.tgz",
@@ -5293,6 +5313,12 @@
"@jridgewell/sourcemap-codec": "^1.4.14"
}
},
+ "node_modules/@jsdevtools/ono": {
+ "version": "7.1.3",
+ "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz",
+ "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==",
+ "license": "MIT"
+ },
"node_modules/@jsep-plugin/assignment": {
"version": "1.3.0",
"license": "MIT",
@@ -5692,6 +5718,315 @@
"version": "v1.15.16",
"license": "Apache-2.0"
},
+ "node_modules/@parcel/watcher": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.5.6.tgz",
+ "integrity": "sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==",
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "dependencies": {
+ "detect-libc": "^2.0.3",
+ "is-glob": "^4.0.3",
+ "node-addon-api": "^7.0.0",
+ "picomatch": "^4.0.3"
+ },
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ },
+ "optionalDependencies": {
+ "@parcel/watcher-android-arm64": "2.5.6",
+ "@parcel/watcher-darwin-arm64": "2.5.6",
+ "@parcel/watcher-darwin-x64": "2.5.6",
+ "@parcel/watcher-freebsd-x64": "2.5.6",
+ "@parcel/watcher-linux-arm-glibc": "2.5.6",
+ "@parcel/watcher-linux-arm-musl": "2.5.6",
+ "@parcel/watcher-linux-arm64-glibc": "2.5.6",
+ "@parcel/watcher-linux-arm64-musl": "2.5.6",
+ "@parcel/watcher-linux-x64-glibc": "2.5.6",
+ "@parcel/watcher-linux-x64-musl": "2.5.6",
+ "@parcel/watcher-win32-arm64": "2.5.6",
+ "@parcel/watcher-win32-ia32": "2.5.6",
+ "@parcel/watcher-win32-x64": "2.5.6"
+ }
+ },
+ "node_modules/@parcel/watcher-android-arm64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-android-arm64/-/watcher-android-arm64-2.5.6.tgz",
+ "integrity": "sha512-YQxSS34tPF/6ZG7r/Ih9xy+kP/WwediEUsqmtf0cuCV5TPPKw/PQHRhueUo6JdeFJaqV3pyjm0GdYjZotbRt/A==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-darwin-arm64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-arm64/-/watcher-darwin-arm64-2.5.6.tgz",
+ "integrity": "sha512-Z2ZdrnwyXvvvdtRHLmM4knydIdU9adO3D4n/0cVipF3rRiwP+3/sfzpAwA/qKFL6i1ModaabkU7IbpeMBgiVEA==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-darwin-x64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-x64/-/watcher-darwin-x64-2.5.6.tgz",
+ "integrity": "sha512-HgvOf3W9dhithcwOWX9uDZyn1lW9R+7tPZ4sug+NGrGIo4Rk1hAXLEbcH1TQSqxts0NYXXlOWqVpvS1SFS4fRg==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-freebsd-x64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-freebsd-x64/-/watcher-freebsd-x64-2.5.6.tgz",
+ "integrity": "sha512-vJVi8yd/qzJxEKHkeemh7w3YAn6RJCtYlE4HPMoVnCpIXEzSrxErBW5SJBgKLbXU3WdIpkjBTeUNtyBVn8TRng==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-arm-glibc": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm-glibc/-/watcher-linux-arm-glibc-2.5.6.tgz",
+ "integrity": "sha512-9JiYfB6h6BgV50CCfasfLf/uvOcJskMSwcdH1PHH9rvS1IrNy8zad6IUVPVUfmXr+u+Km9IxcfMLzgdOudz9EQ==",
+ "cpu": [
+ "arm"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-arm-musl": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm-musl/-/watcher-linux-arm-musl-2.5.6.tgz",
+ "integrity": "sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==",
+ "cpu": [
+ "arm"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-arm64-glibc": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-glibc/-/watcher-linux-arm64-glibc-2.5.6.tgz",
+ "integrity": "sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-arm64-musl": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-musl/-/watcher-linux-arm64-musl-2.5.6.tgz",
+ "integrity": "sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-x64-glibc": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-glibc/-/watcher-linux-x64-glibc-2.5.6.tgz",
+ "integrity": "sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-linux-x64-musl": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-musl/-/watcher-linux-x64-musl-2.5.6.tgz",
+ "integrity": "sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-win32-arm64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-arm64/-/watcher-win32-arm64-2.5.6.tgz",
+ "integrity": "sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==",
+ "cpu": [
+ "arm64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-win32-ia32": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-ia32/-/watcher-win32-ia32-2.5.6.tgz",
+ "integrity": "sha512-k35yLp1ZMwwee3Ez/pxBi5cf4AoBKYXj00CZ80jUz5h8prpiaQsiRPKQMxoLstNuqe2vR4RNPEAEcjEFzhEz/g==",
+ "cpu": [
+ "ia32"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher-win32-x64": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-x64/-/watcher-win32-x64-2.5.6.tgz",
+ "integrity": "sha512-hbQlYcCq5dlAX9Qx+kFb0FHue6vbjlf0FrNzSKdYK2APUf7tGfGxQCk2ihEREmbR6ZMc0MVAD5RIX/41gpUzTw==",
+ "cpu": [
+ "x64"
+ ],
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">= 10.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/parcel"
+ }
+ },
+ "node_modules/@parcel/watcher/node_modules/picomatch": {
+ "version": "4.0.4",
+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+ "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+ "license": "MIT",
+ "optional": true,
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/jonschlinkert"
+ }
+ },
"node_modules/@pkgr/core": {
"version": "0.1.1",
"dev": true,
@@ -5837,6 +6172,32 @@
"node": ">=10"
}
},
+ "node_modules/@reduxjs/toolkit": {
+ "version": "2.11.2",
+ "resolved": "https://registry.npmjs.org/@reduxjs/toolkit/-/toolkit-2.11.2.tgz",
+ "integrity": "sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@standard-schema/spec": "^1.0.0",
+ "@standard-schema/utils": "^0.3.0",
+ "immer": "^11.0.0",
+ "redux": "^5.0.1",
+ "redux-thunk": "^3.1.0",
+ "reselect": "^5.1.0"
+ },
+ "peerDependencies": {
+ "react": "^16.9.0 || ^17.0.0 || ^18 || ^19",
+ "react-redux": "^7.2.1 || ^8.1.3 || ^9.0.0"
+ },
+ "peerDependenciesMeta": {
+ "react": {
+ "optional": true
+ },
+ "react-redux": {
+ "optional": true
+ }
+ }
+ },
"node_modules/@restart/context": {
"version": "2.1.4",
"resolved": "https://registry.npmjs.org/@restart/context/-/context-2.1.4.tgz",
@@ -6037,6 +6398,12 @@
"resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.0.0.tgz",
"integrity": "sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA=="
},
+ "node_modules/@standard-schema/utils": {
+ "version": "0.3.0",
+ "resolved": "https://registry.npmjs.org/@standard-schema/utils/-/utils-0.3.0.tgz",
+ "integrity": "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==",
+ "license": "MIT"
+ },
"node_modules/@svgr/babel-plugin-add-jsx-attribute": {
"version": "8.0.0",
"resolved": "https://registry.npmjs.org/@svgr/babel-plugin-add-jsx-attribute/-/babel-plugin-add-jsx-attribute-8.0.0.tgz",
@@ -7457,6 +7824,12 @@
"version": "3.0.3",
"license": "MIT"
},
+ "node_modules/@types/use-sync-external-store": {
+ "version": "0.0.6",
+ "resolved": "https://registry.npmjs.org/@types/use-sync-external-store/-/use-sync-external-store-0.0.6.tgz",
+ "integrity": "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==",
+ "license": "MIT"
+ },
"node_modules/@types/warning": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/@types/warning/-/warning-3.0.3.tgz",
@@ -7748,6 +8121,20 @@
"url": "https://github.com/sponsors/epoberezkin"
}
},
+ "node_modules/ajv-draft-04": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz",
+ "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==",
+ "license": "MIT",
+ "peerDependencies": {
+ "ajv": "^8.5.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
"node_modules/ajv-formats": {
"version": "2.1.1",
"license": "MIT",
@@ -7809,6 +8196,15 @@
"algoliasearch": ">= 3.1 < 6"
}
},
+ "node_modules/allof-merge": {
+ "version": "0.6.8",
+ "resolved": "https://registry.npmjs.org/allof-merge/-/allof-merge-0.6.8.tgz",
+ "integrity": "sha512-RJrHVDqITsU1kjE2L7s1hy4AYZSTlO1m9jTleYhVCEOfOpbbygRGfcEgrp+bW3oX/PcMUwVkt6MSJyXoyI6lRA==",
+ "license": "MIT",
+ "dependencies": {
+ "json-crawl": "^0.5.3"
+ }
+ },
"node_modules/anchor-markdown-header": {
"version": "0.5.7",
"dev": true,
@@ -7897,6 +8293,12 @@
"node": ">=4"
}
},
+ "node_modules/any-promise": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz",
+ "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==",
+ "license": "MIT"
+ },
"node_modules/anymatch": {
"version": "3.1.3",
"license": "ISC",
@@ -8007,6 +8409,12 @@
"astring": "bin/astring"
}
},
+ "node_modules/async": {
+ "version": "3.2.6",
+ "resolved": "https://registry.npmjs.org/async/-/async-3.2.6.tgz",
+ "integrity": "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==",
+ "license": "MIT"
+ },
"node_modules/asynckit": {
"version": "0.4.0",
"license": "MIT"
@@ -8889,6 +9297,15 @@
"url": "https://github.com/sponsors/wooorm"
}
},
+ "node_modules/charset": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/charset/-/charset-1.0.1.tgz",
+ "integrity": "sha512-6dVyOOYjpfFcL1Y4qChrAoQLRHvj2ziyhcm0QJlhOcAhykL/k1kTUPbeo+87MNRTRdk2OIIsIXbuF3x2wi5EXg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=4.0.0"
+ }
+ },
"node_modules/cheerio": {
"version": "1.0.0-rc.12",
"resolved": "https://registry.npmjs.org/cheerio/-/cheerio-1.0.0-rc.12.tgz",
@@ -9503,6 +9920,18 @@
"resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.6.tgz",
"integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ=="
},
+ "node_modules/copy-text-to-clipboard": {
+ "version": "3.2.2",
+ "resolved": "https://registry.npmjs.org/copy-text-to-clipboard/-/copy-text-to-clipboard-3.2.2.tgz",
+ "integrity": "sha512-T6SqyLd1iLuqPA90J5N4cTalrtovCySh58iiZDGJ6FGznbclKh4UI+FGacQSgFzwKG77W7XT5gwbVEbd9cIH1A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
"node_modules/copy-webpack-plugin": {
"version": "11.0.0",
"resolved": "https://registry.npmjs.org/copy-webpack-plugin/-/copy-webpack-plugin-11.0.0.tgz",
@@ -9729,6 +10158,12 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/crypto-js": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
+ "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
+ "license": "MIT"
+ },
"node_modules/crypto-random-string": {
"version": "4.0.0",
"license": "MIT",
@@ -10912,7 +11347,7 @@
"version": "2.0.4",
"resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.4.tgz",
"integrity": "sha512-3UDv+G9CsCKO1WKMGw9fwq/SWJYbI0c5Y7LU1AXYoDdbhE2AHQ6N6Nb34sG8Fj7T5APy8qXDCKuuIHd1BR0tVA==",
- "dev": true,
+ "devOptional": true,
"license": "Apache-2.0",
"engines": {
"node": ">=8"
@@ -10931,6 +11366,18 @@
"resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz",
"integrity": "sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g=="
},
+ "node_modules/detect-package-manager": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/detect-package-manager/-/detect-package-manager-3.0.2.tgz",
+ "integrity": "sha512-8JFjJHutStYrfWwzfretQoyNGoZVW1Fsrp4JO9spa7h/fBfwgTMEIy4/LBzRDGsxwVPHU0q+T9YvwLDJoOApLQ==",
+ "license": "MIT",
+ "dependencies": {
+ "execa": "^5.1.1"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/detect-port": {
"version": "1.6.1",
"license": "MIT",
@@ -10979,41 +11426,156 @@
"dev": true,
"license": "MIT",
"engines": {
- "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+ "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+ }
+ },
+ "node_modules/diffie-hellman": {
+ "version": "5.0.3",
+ "license": "MIT",
+ "dependencies": {
+ "bn.js": "^4.1.0",
+ "miller-rabin": "^4.0.0",
+ "randombytes": "^2.0.0"
+ }
+ },
+ "node_modules/diffie-hellman/node_modules/bn.js": {
+ "version": "4.12.0",
+ "license": "MIT"
+ },
+ "node_modules/dir-glob": {
+ "version": "3.0.1",
+ "license": "MIT",
+ "dependencies": {
+ "path-type": "^4.0.0"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/dns-packet": {
+ "version": "5.6.1",
+ "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-5.6.1.tgz",
+ "integrity": "sha512-l4gcSouhcgIKRvyy99RNVOgxXiicE+2jZoNmaNmZ6JXiGajBOJAesk1OBlJuM5k2c+eudGdLxDqXuPCKIj6kpw==",
+ "dependencies": {
+ "@leichtgewicht/ip-codec": "^2.0.1"
+ },
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/docusaurus-plugin-openapi-docs": {
+ "version": "4.7.1",
+ "resolved": "https://registry.npmjs.org/docusaurus-plugin-openapi-docs/-/docusaurus-plugin-openapi-docs-4.7.1.tgz",
+ "integrity": "sha512-RpqvTEnhIfdSuTn/Fa/8bmxeufijLL9HCRb//ELD33AKqEbCw147SKR/CqWu4H4gwi50FZLUbiHKZJbPtXLt9Q==",
+ "license": "MIT",
+ "dependencies": {
+ "@apidevtools/json-schema-ref-parser": "^11.5.4",
+ "@redocly/openapi-core": "^1.34.3",
+ "allof-merge": "^0.6.6",
+ "chalk": "^4.1.2",
+ "clsx": "^2.1.1",
+ "fs-extra": "^11.3.0",
+ "json-pointer": "^0.6.2",
+ "json5": "^2.2.3",
+ "lodash": "^4.17.21",
+ "mustache": "^4.2.0",
+ "openapi-to-postmanv2": "^5.0.0",
+ "postman-collection": "^5.0.2",
+ "slugify": "^1.6.6",
+ "swagger2openapi": "^7.0.8",
+ "xml-formatter": "^3.6.6"
+ },
+ "engines": {
+ "node": ">=14"
+ },
+ "peerDependencies": {
+ "@docusaurus/plugin-content-docs": "^3.5.0",
+ "@docusaurus/utils": "^3.5.0",
+ "@docusaurus/utils-validation": "^3.5.0",
+ "react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+ }
+ },
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/@apidevtools/json-schema-ref-parser": {
+ "version": "11.9.3",
+ "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-11.9.3.tgz",
+ "integrity": "sha512-60vepv88RwcJtSHrD6MjIL6Ta3SOYbgfnkHb+ppAVK+o9mXprRtulx7VlRl3lN3bbvysAfCS7WMVfhUYemB0IQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@jsdevtools/ono": "^7.1.3",
+ "@types/json-schema": "^7.0.15",
+ "js-yaml": "^4.1.0"
+ },
+ "engines": {
+ "node": ">= 16"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/philsturgeon"
+ }
+ },
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/@redocly/config": {
+ "version": "0.22.0",
+ "resolved": "https://registry.npmjs.org/@redocly/config/-/config-0.22.0.tgz",
+ "integrity": "sha512-gAy93Ddo01Z3bHuVdPWfCwzgfaYgMdaZPcfL7JZ7hWJoK9V0lXDbigTWkhiPFAaLWzbOJ+kbUQG1+XwIm0KRGQ==",
+ "license": "MIT"
+ },
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/@redocly/openapi-core": {
+ "version": "1.34.11",
+ "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-1.34.11.tgz",
+ "integrity": "sha512-V09ayfnb5GyysmvARbt+voFZAjGcf7hSYxOYxSkCc4fbH/DTfq5YWoec8cflvmHHqyIFbqvmGKmYFzqhr9zxDg==",
+ "license": "MIT",
+ "dependencies": {
+ "@redocly/ajv": "8.11.2",
+ "@redocly/config": "0.22.0",
+ "colorette": "1.4.0",
+ "https-proxy-agent": "7.0.6",
+ "js-levenshtein": "1.1.6",
+ "js-yaml": "4.1.1",
+ "minimatch": "5.1.9",
+ "pluralize": "8.0.0",
+ "yaml-ast-parser": "0.0.43"
+ },
+ "engines": {
+ "node": ">=18.17.0",
+ "npm": ">=9.5.0"
}
},
- "node_modules/diffie-hellman": {
- "version": "5.0.3",
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/brace-expansion": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz",
+ "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==",
"license": "MIT",
"dependencies": {
- "bn.js": "^4.1.0",
- "miller-rabin": "^4.0.0",
- "randombytes": "^2.0.0"
+ "balanced-match": "^1.0.0"
}
},
- "node_modules/diffie-hellman/node_modules/bn.js": {
- "version": "4.12.0",
- "license": "MIT"
- },
- "node_modules/dir-glob": {
- "version": "3.0.1",
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/clsx": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+ "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
"license": "MIT",
- "dependencies": {
- "path-type": "^4.0.0"
- },
"engines": {
- "node": ">=8"
+ "node": ">=6"
}
},
- "node_modules/dns-packet": {
- "version": "5.6.1",
- "resolved": "https://registry.npmjs.org/dns-packet/-/dns-packet-5.6.1.tgz",
- "integrity": "sha512-l4gcSouhcgIKRvyy99RNVOgxXiicE+2jZoNmaNmZ6JXiGajBOJAesk1OBlJuM5k2c+eudGdLxDqXuPCKIj6kpw==",
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/minimatch": {
+ "version": "5.1.9",
+ "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.9.tgz",
+ "integrity": "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw==",
+ "license": "ISC",
"dependencies": {
- "@leichtgewicht/ip-codec": "^2.0.1"
+ "brace-expansion": "^2.0.1"
},
"engines": {
- "node": ">=6"
+ "node": ">=10"
+ }
+ },
+ "node_modules/docusaurus-plugin-openapi-docs/node_modules/slugify": {
+ "version": "1.6.9",
+ "resolved": "https://registry.npmjs.org/slugify/-/slugify-1.6.9.tgz",
+ "integrity": "sha512-vZ7rfeehZui7wQs438JXBckYLkIIdfHOXsaVEUMyS5fHo1483l1bMdo0EDSWYclY0yZKFOipDy4KHuKs6ssvdg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8.0.0"
}
},
"node_modules/docusaurus-plugin-redoc": {
@@ -11032,6 +11594,80 @@
"@docusaurus/utils": "^3.6.0"
}
},
+ "node_modules/docusaurus-plugin-sass": {
+ "version": "0.2.6",
+ "resolved": "https://registry.npmjs.org/docusaurus-plugin-sass/-/docusaurus-plugin-sass-0.2.6.tgz",
+ "integrity": "sha512-2hKQQDkrufMong9upKoG/kSHJhuwd+FA3iAe/qzS/BmWpbIpe7XKmq5wlz4J5CJaOPu4x+iDJbgAxZqcoQf0kg==",
+ "license": "MIT",
+ "peer": true,
+ "dependencies": {
+ "sass-loader": "^16.0.2"
+ },
+ "peerDependencies": {
+ "@docusaurus/core": "^2.0.0-beta || ^3.0.0-alpha",
+ "sass": "^1.30.0"
+ }
+ },
+ "node_modules/docusaurus-theme-openapi-docs": {
+ "version": "4.7.1",
+ "resolved": "https://registry.npmjs.org/docusaurus-theme-openapi-docs/-/docusaurus-theme-openapi-docs-4.7.1.tgz",
+ "integrity": "sha512-OPydf11LoEY3fdxaoqCVO+qCk7LBo6l6s28UvHJ5mIN/2xu+dOOio9+xnKZ5FIPOlD+dx0gVSKzaVCi/UFTxlg==",
+ "license": "MIT",
+ "dependencies": {
+ "@hookform/error-message": "^2.0.1",
+ "@reduxjs/toolkit": "^2.8.2",
+ "allof-merge": "^0.6.6",
+ "buffer": "^6.0.3",
+ "clsx": "^2.1.1",
+ "copy-text-to-clipboard": "^3.2.0",
+ "crypto-js": "^4.2.0",
+ "file-saver": "^2.0.5",
+ "lodash": "^4.17.21",
+ "pako": "^2.1.0",
+ "postman-code-generators": "^2.0.0",
+ "postman-collection": "^5.0.2",
+ "prism-react-renderer": "^2.4.1",
+ "process": "^0.11.10",
+ "react-hook-form": "^7.59.0",
+ "react-live": "^4.1.8",
+ "react-magic-dropzone": "^1.0.1",
+ "react-markdown": "^10.1.0",
+ "react-modal": "^3.16.3",
+ "react-redux": "^9.2.0",
+ "rehype-raw": "^7.0.0",
+ "remark-gfm": "4.0.1",
+ "sass": "^1.89.2",
+ "sass-loader": "^16.0.5",
+ "unist-util-visit": "^5.0.0",
+ "url": "^0.11.4",
+ "xml-formatter": "^3.6.6"
+ },
+ "engines": {
+ "node": ">=14"
+ },
+ "peerDependencies": {
+ "@docusaurus/theme-common": "^3.5.0",
+ "docusaurus-plugin-openapi-docs": "^4.0.0",
+ "docusaurus-plugin-sass": "^0.2.3",
+ "react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+ "react-dom": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+ }
+ },
+ "node_modules/docusaurus-theme-openapi-docs/node_modules/clsx": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+ "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/docusaurus-theme-openapi-docs/node_modules/pako": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/pako/-/pako-2.1.0.tgz",
+ "integrity": "sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==",
+ "license": "(MIT AND Zlib)"
+ },
"node_modules/docusaurus-theme-redoc": {
"version": "2.5.0",
"resolved": "https://registry.npmjs.org/docusaurus-theme-redoc/-/docusaurus-theme-redoc-2.5.0.tgz",
@@ -11793,6 +12429,12 @@
"url": "https://github.com/sindresorhus/execa?sponsor=1"
}
},
+ "node_modules/exenv": {
+ "version": "1.2.2",
+ "resolved": "https://registry.npmjs.org/exenv/-/exenv-1.2.2.tgz",
+ "integrity": "sha512-Z+ktTxTwv9ILfgKCk32OX3n/doe+OcLTRtqK9pcL+JsP3J1/VW8Uvl4ZjLlKqeW4rzK4oesDOGMEMRIZqtP4Iw==",
+ "license": "BSD-3-Clause"
+ },
"node_modules/exit": {
"version": "0.1.2",
"dev": true,
@@ -12108,6 +12750,21 @@
"url": "https://opencollective.com/webpack"
}
},
+ "node_modules/file-saver": {
+ "version": "2.0.5",
+ "resolved": "https://registry.npmjs.org/file-saver/-/file-saver-2.0.5.tgz",
+ "integrity": "sha512-P9bmyZ3h/PRG+Nzga+rbdI4OEpNDzAVyy74uVO9ATgzLK6VtAsYybF/+TOCvrc0MO793d6+42lLyZTw7/ArVzA==",
+ "license": "MIT"
+ },
+ "node_modules/file-type": {
+ "version": "3.9.0",
+ "resolved": "https://registry.npmjs.org/file-type/-/file-type-3.9.0.tgz",
+ "integrity": "sha512-RLoqTXE8/vPmMuTI88DAzhMYC99I8BWv7zYP4A1puo5HIjEJ5EX48ighy4ZyKMG9EDXxBgW6e++cn7d1xuFghA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
"node_modules/fill-range": {
"version": "7.1.1",
"license": "MIT",
@@ -12285,7 +12942,9 @@
"license": "MIT"
},
"node_modules/fs-extra": {
- "version": "11.2.0",
+ "version": "11.3.4",
+ "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.4.tgz",
+ "integrity": "sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==",
"license": "MIT",
"dependencies": {
"graceful-fs": "^4.2.0",
@@ -12298,7 +12957,6 @@
},
"node_modules/fs.realpath": {
"version": "1.0.0",
- "dev": true,
"license": "ISC"
},
"node_modules/fsevents": {
@@ -12458,7 +13116,6 @@
},
"node_modules/glob": {
"version": "7.2.3",
- "dev": true,
"license": "ISC",
"dependencies": {
"fs.realpath": "^1.0.0",
@@ -12617,6 +13274,15 @@
"version": "4.2.11",
"license": "ISC"
},
+ "node_modules/graphlib": {
+ "version": "2.1.8",
+ "resolved": "https://registry.npmjs.org/graphlib/-/graphlib-2.1.8.tgz",
+ "integrity": "sha512-jcLLfkpoVGmH7/InMC/1hIvOPSUh38oJtGhvrOFGzioE1DZ+0YW16RgmOJhHiuWTvGiJQ9Z1Ik43JvkRPRvE+A==",
+ "license": "MIT",
+ "dependencies": {
+ "lodash": "^4.17.15"
+ }
+ },
"node_modules/gray-matter": {
"version": "4.0.3",
"license": "MIT",
@@ -13061,6 +13727,16 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/html-url-attributes": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",
+ "integrity": "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==",
+ "license": "MIT",
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/unified"
+ }
+ },
"node_modules/html-void-elements": {
"version": "3.0.0",
"license": "MIT",
@@ -13219,6 +13895,12 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/http-reasons": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/http-reasons/-/http-reasons-0.1.0.tgz",
+ "integrity": "sha512-P6kYh0lKZ+y29T2Gqz+RlC9WBLhKe8kDmcJ+A+611jFfxdPsbMRQ5aNmFRM3lENqFkK+HTTL+tlQviAiv0AbLQ==",
+ "license": "Apache-2.0"
+ },
"node_modules/http2-client": {
"version": "1.3.5",
"resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz",
@@ -13341,6 +14023,22 @@
"node": ">=16.x"
}
},
+ "node_modules/immer": {
+ "version": "11.1.4",
+ "resolved": "https://registry.npmjs.org/immer/-/immer-11.1.4.tgz",
+ "integrity": "sha512-XREFCPo6ksxVzP4E0ekD5aMdf8WMwmdNaz6vuvxgI40UaEiu6q3p8X52aU6GdyvLY3XXX/8R7JOTXStz/nBbRw==",
+ "license": "MIT",
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/immer"
+ }
+ },
+ "node_modules/immutable": {
+ "version": "5.1.5",
+ "resolved": "https://registry.npmjs.org/immutable/-/immutable-5.1.5.tgz",
+ "integrity": "sha512-t7xcm2siw+hlUM68I+UEOK+z84RzmN59as9DZ7P1l0994DKUWV7UXBMQZVxaoMSRQ+PBZbHCOoBt7a2wxOMt+A==",
+ "license": "MIT"
+ },
"node_modules/import-fresh": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
@@ -13418,7 +14116,6 @@
},
"node_modules/inflight": {
"version": "1.0.6",
- "dev": true,
"license": "ISC",
"dependencies": {
"once": "^1.3.0",
@@ -13458,6 +14155,15 @@
"node": ">=12"
}
},
+ "node_modules/interpret": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz",
+ "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 0.10"
+ }
+ },
"node_modules/invariant": {
"version": "2.2.4",
"license": "MIT",
@@ -14750,6 +15456,15 @@
"version": "3.0.1",
"license": "MIT"
},
+ "node_modules/json-crawl": {
+ "version": "0.5.3",
+ "resolved": "https://registry.npmjs.org/json-crawl/-/json-crawl-0.5.3.tgz",
+ "integrity": "sha512-BEjjCw8c7SxzNK4orhlWD5cXQh8vCk2LqDr4WgQq4CV+5dvopeYwt1Tskg67SuSLKvoFH5g0yuYtg7rcfKV6YA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=14.0.0"
+ }
+ },
"node_modules/json-loader": {
"version": "0.5.7",
"license": "MIT"
@@ -15343,6 +16058,15 @@
"uc.micro": "^1.0.1"
}
},
+ "node_modules/liquid-json": {
+ "version": "0.3.1",
+ "resolved": "https://registry.npmjs.org/liquid-json/-/liquid-json-0.3.1.tgz",
+ "integrity": "sha512-wUayTU8MS827Dam6MxgD72Ui+KOSF+u/eIqpatOtjnvgJ0+mnDq33uC2M7J0tPK+upe/DpUAuK4JUU89iBoNKQ==",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=4"
+ }
+ },
"node_modules/load-json-file": {
"version": "4.0.0",
"dev": true,
@@ -17738,6 +18462,15 @@
"node": ">= 0.6"
}
},
+ "node_modules/mime-format": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/mime-format/-/mime-format-2.0.2.tgz",
+ "integrity": "sha512-Y5ERWVcyh3sby9Fx2U5F1yatiTFjNsqF5NltihTWI9QgNtr5o3dbCZdcKa1l2wyfhnwwoP9HGNxga7LqZLA6gw==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "charset": "^1.0.0"
+ }
+ },
"node_modules/mime-types": {
"version": "2.1.35",
"license": "MIT",
@@ -17970,6 +18703,26 @@
"multicast-dns": "cli.js"
}
},
+ "node_modules/mustache": {
+ "version": "4.2.0",
+ "resolved": "https://registry.npmjs.org/mustache/-/mustache-4.2.0.tgz",
+ "integrity": "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==",
+ "license": "MIT",
+ "bin": {
+ "mustache": "bin/mustache"
+ }
+ },
+ "node_modules/mz": {
+ "version": "2.7.0",
+ "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz",
+ "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==",
+ "license": "MIT",
+ "dependencies": {
+ "any-promise": "^1.0.0",
+ "object-assign": "^4.0.1",
+ "thenify-all": "^1.0.0"
+ }
+ },
"node_modules/nanoid": {
"version": "3.3.11",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
@@ -18005,6 +18758,15 @@
"version": "2.6.2",
"license": "MIT"
},
+ "node_modules/neotraverse": {
+ "version": "0.6.15",
+ "resolved": "https://registry.npmjs.org/neotraverse/-/neotraverse-0.6.15.tgz",
+ "integrity": "sha512-HZpdkco+JeXq0G+WWpMJ4NsX3pqb5O7eR9uGz3FfoFt+LYzU8iRWp49nJtud6hsDoywM8tIrDo3gjgmOqJA8LA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 10"
+ }
+ },
"node_modules/net": {
"version": "1.0.2",
"license": "MIT"
@@ -18022,6 +18784,13 @@
"tslib": "^2.0.3"
}
},
+ "node_modules/node-addon-api": {
+ "version": "7.1.1",
+ "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+ "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+ "license": "MIT",
+ "optional": true
+ },
"node_modules/node-emoji": {
"version": "2.2.0",
"license": "MIT",
@@ -18464,6 +19233,35 @@
"url": "https://github.com/Mermade/oas-kit?sponsor=1"
}
},
+ "node_modules/oas-resolver-browser": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/oas-resolver-browser/-/oas-resolver-browser-2.5.6.tgz",
+ "integrity": "sha512-Jw5elT/kwUJrnGaVuRWe1D7hmnYWB8rfDDjBnpQ+RYY/dzAewGXeTexXzt4fGEo6PUE4eqKqPWF79MZxxvMppA==",
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "node-fetch-h2": "^2.3.0",
+ "oas-kit-common": "^1.0.8",
+ "path-browserify": "^1.0.1",
+ "reftools": "^1.1.9",
+ "yaml": "^1.10.0",
+ "yargs": "^17.0.1"
+ },
+ "bin": {
+ "resolve": "resolve.js"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-resolver-browser/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/oas-resolver/node_modules/yaml": {
"version": "1.10.2",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
@@ -18517,6 +19315,15 @@
"node": ">=0.10.0"
}
},
+ "node_modules/object-hash": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-3.0.0.tgz",
+ "integrity": "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/object-inspect": {
"version": "1.13.3",
"license": "MIT",
@@ -18644,6 +19451,64 @@
"json-pointer": "0.6.2"
}
},
+ "node_modules/openapi-to-postmanv2": {
+ "version": "5.8.0",
+ "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-5.8.0.tgz",
+ "integrity": "sha512-7f02ypBlAx4G9z3bP/uDk8pBwRbYt97Eoso8XJLyclfyRvCC+CvERLUl0MD0x+GoumpkJYnQ0VGdib/kwtUdUw==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "ajv": "^8.11.0",
+ "ajv-draft-04": "1.0.0",
+ "ajv-formats": "2.1.1",
+ "async": "3.2.6",
+ "commander": "2.20.3",
+ "graphlib": "2.1.8",
+ "js-yaml": "4.1.0",
+ "json-pointer": "0.6.2",
+ "json-schema-merge-allof": "0.8.1",
+ "lodash": "4.17.21",
+ "neotraverse": "0.6.15",
+ "oas-resolver-browser": "2.5.6",
+ "object-hash": "3.0.0",
+ "path-browserify": "1.0.1",
+ "postman-collection": "^5.0.0",
+ "swagger2openapi": "7.0.8",
+ "yaml": "1.10.2"
+ },
+ "bin": {
+ "openapi2postmanv2": "bin/openapi2postmanv2.js"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/commander": {
+ "version": "2.20.3",
+ "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+ "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
+ "license": "MIT"
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/js-yaml": {
+ "version": "4.1.0",
+ "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
+ "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+ "license": "MIT",
+ "dependencies": {
+ "argparse": "^2.0.1"
+ },
+ "bin": {
+ "js-yaml": "bin/js-yaml.js"
+ }
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/yaml": {
+ "version": "1.10.2",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
+ "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==",
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/opener": {
"version": "1.5.2",
"license": "(WTFPL OR MIT)",
@@ -19034,7 +19899,6 @@
},
"node_modules/path-is-absolute": {
"version": "1.0.1",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">=0.10.0"
@@ -19143,7 +20007,6 @@
},
"node_modules/pirates": {
"version": "4.0.6",
- "dev": true,
"license": "MIT",
"engines": {
"node": ">= 6"
@@ -20756,19 +21619,109 @@
"postcss": "^8.4.31"
}
},
- "node_modules/postcss-value-parser": {
- "version": "4.2.0",
- "license": "MIT"
+ "node_modules/postcss-value-parser": {
+ "version": "4.2.0",
+ "license": "MIT"
+ },
+ "node_modules/postcss-zindex": {
+ "version": "6.0.2",
+ "resolved": "https://registry.npmjs.org/postcss-zindex/-/postcss-zindex-6.0.2.tgz",
+ "integrity": "sha512-5BxW9l1evPB/4ZIc+2GobEBoKC+h8gPGCMi+jxsYvd2x0mjq7wazk6DrP71pStqxE9Foxh5TVnonbWpFZzXaYg==",
+ "engines": {
+ "node": "^14 || ^16 || >=18.0"
+ },
+ "peerDependencies": {
+ "postcss": "^8.4.31"
+ }
+ },
+ "node_modules/postman-code-generators": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/postman-code-generators/-/postman-code-generators-2.1.1.tgz",
+ "integrity": "sha512-+egQK1Jf9a92QP23vRTKcDLOthIQmI7WI4czEsZq/wgguLMnVHJ26KlT8AVtpAdVw28hqUbHwicerYxRWCfjoA==",
+ "hasInstallScript": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "async": "^3.2.2",
+ "detect-package-manager": "^3.0.2",
+ "lodash": "^4.17.21",
+ "postman-collection": "^5.0.0",
+ "shelljs": "^0.8.5"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/postman-collection": {
+ "version": "5.3.0",
+ "resolved": "https://registry.npmjs.org/postman-collection/-/postman-collection-5.3.0.tgz",
+ "integrity": "sha512-PMa5vRheqDFfS1bkRg8WBidWxunRA80sT5YNLP27YC5+ycyfiLMCwPnqQd1zfvxkGk04Pr9UronWmmgsbpsVyQ==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@faker-js/faker": "5.5.3",
+ "file-type": "3.9.0",
+ "http-reasons": "0.1.0",
+ "iconv-lite": "0.6.3",
+ "liquid-json": "0.3.1",
+ "lodash": "4.17.23",
+ "mime": "3.0.0",
+ "mime-format": "2.0.2",
+ "postman-url-encoder": "3.0.8",
+ "semver": "7.7.1",
+ "uuid": "8.3.2"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/postman-collection/node_modules/lodash": {
+ "version": "4.17.23",
+ "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz",
+ "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==",
+ "license": "MIT"
+ },
+ "node_modules/postman-collection/node_modules/mime": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz",
+ "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==",
+ "license": "MIT",
+ "bin": {
+ "mime": "cli.js"
+ },
+ "engines": {
+ "node": ">=10.0.0"
+ }
+ },
+ "node_modules/postman-collection/node_modules/semver": {
+ "version": "7.7.1",
+ "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.1.tgz",
+ "integrity": "sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA==",
+ "license": "ISC",
+ "bin": {
+ "semver": "bin/semver.js"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/postman-collection/node_modules/uuid": {
+ "version": "8.3.2",
+ "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+ "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
+ "license": "MIT",
+ "bin": {
+ "uuid": "dist/bin/uuid"
+ }
},
- "node_modules/postcss-zindex": {
- "version": "6.0.2",
- "resolved": "https://registry.npmjs.org/postcss-zindex/-/postcss-zindex-6.0.2.tgz",
- "integrity": "sha512-5BxW9l1evPB/4ZIc+2GobEBoKC+h8gPGCMi+jxsYvd2x0mjq7wazk6DrP71pStqxE9Foxh5TVnonbWpFZzXaYg==",
- "engines": {
- "node": "^14 || ^16 || >=18.0"
+ "node_modules/postman-url-encoder": {
+ "version": "3.0.8",
+ "resolved": "https://registry.npmjs.org/postman-url-encoder/-/postman-url-encoder-3.0.8.tgz",
+ "integrity": "sha512-EOgUMBazo7JNP4TDrd64TsooCiWzzo4143Ws8E8WYGEpn2PKpq+S4XRTDhuRTYHm3VKOpUZs7ZYZq7zSDuesqA==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "punycode": "^2.3.1"
},
- "peerDependencies": {
- "postcss": "^8.4.31"
+ "engines": {
+ "node": ">=10"
}
},
"node_modules/prettier": {
@@ -21297,6 +22250,22 @@
"react-dom": "^16.6.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
}
},
+ "node_modules/react-hook-form": {
+ "version": "7.72.1",
+ "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.72.1.tgz",
+ "integrity": "sha512-RhwBoy2ygeVZje+C+bwJ8g0NjTdBmDlJvAUHTxRjTmSUKPYsKfMphkS2sgEMotsY03bP358yEYlnUeZy//D9Ig==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/react-hook-form"
+ },
+ "peerDependencies": {
+ "react": "^16.8.0 || ^17 || ^18 || ^19"
+ }
+ },
"node_modules/react-is": {
"version": "18.3.1",
"license": "MIT"
@@ -21318,6 +22287,25 @@
"integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==",
"license": "MIT"
},
+ "node_modules/react-live": {
+ "version": "4.1.8",
+ "resolved": "https://registry.npmjs.org/react-live/-/react-live-4.1.8.tgz",
+ "integrity": "sha512-B2SgNqwPuS2ekqj4lcxi5TibEcjWkdVyYykBEUBshPAPDQ527x2zPEZg560n8egNtAjUpwXFQm7pcXV65aAYmg==",
+ "license": "MIT",
+ "dependencies": {
+ "prism-react-renderer": "^2.4.0",
+ "sucrase": "^3.35.0",
+ "use-editable": "^2.3.3"
+ },
+ "engines": {
+ "node": ">= 0.12.0",
+ "npm": ">= 2.0.0"
+ },
+ "peerDependencies": {
+ "react": ">=18.0.0",
+ "react-dom": ">=18.0.0"
+ }
+ },
"node_modules/react-loadable": {
"name": "@docusaurus/react-loadable",
"version": "6.0.0",
@@ -21343,6 +22331,55 @@
"webpack": ">=4.41.1 || 5.x"
}
},
+ "node_modules/react-magic-dropzone": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/react-magic-dropzone/-/react-magic-dropzone-1.0.1.tgz",
+ "integrity": "sha512-0BIROPARmXHpk4AS3eWBOsewxoM5ndk2psYP/JmbCq8tz3uR2LIV1XiroZ9PKrmDRMctpW+TvsBCtWasuS8vFA==",
+ "license": "MIT"
+ },
+ "node_modules/react-markdown": {
+ "version": "10.1.0",
+ "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz",
+ "integrity": "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/hast": "^3.0.0",
+ "@types/mdast": "^4.0.0",
+ "devlop": "^1.0.0",
+ "hast-util-to-jsx-runtime": "^2.0.0",
+ "html-url-attributes": "^3.0.0",
+ "mdast-util-to-hast": "^13.0.0",
+ "remark-parse": "^11.0.0",
+ "remark-rehype": "^11.0.0",
+ "unified": "^11.0.0",
+ "unist-util-visit": "^5.0.0",
+ "vfile": "^6.0.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/unified"
+ },
+ "peerDependencies": {
+ "@types/react": ">=18",
+ "react": ">=18"
+ }
+ },
+ "node_modules/react-modal": {
+ "version": "3.16.3",
+ "resolved": "https://registry.npmjs.org/react-modal/-/react-modal-3.16.3.tgz",
+ "integrity": "sha512-yCYRJB5YkeQDQlTt17WGAgFJ7jr2QYcWa1SHqZ3PluDmnKJ/7+tVU+E6uKyZ0nODaeEj+xCpK4LcSnKXLMC0Nw==",
+ "license": "MIT",
+ "dependencies": {
+ "exenv": "^1.2.0",
+ "prop-types": "^15.7.2",
+ "react-lifecycles-compat": "^3.0.0",
+ "warning": "^4.0.3"
+ },
+ "peerDependencies": {
+ "react": "^0.14.0 || ^15.0.0 || ^16 || ^17 || ^18 || ^19",
+ "react-dom": "^0.14.0 || ^15.0.0 || ^16 || ^17 || ^18 || ^19"
+ }
+ },
"node_modules/react-overlays": {
"version": "5.2.1",
"resolved": "https://registry.npmjs.org/react-overlays/-/react-overlays-5.2.1.tgz",
@@ -21363,6 +22400,29 @@
"react-dom": ">=16.3.0"
}
},
+ "node_modules/react-redux": {
+ "version": "9.2.0",
+ "resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
+ "integrity": "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/use-sync-external-store": "^0.0.6",
+ "use-sync-external-store": "^1.4.0"
+ },
+ "peerDependencies": {
+ "@types/react": "^18.2.25 || ^19",
+ "react": "^18.0 || ^19",
+ "redux": "^5.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@types/react": {
+ "optional": true
+ },
+ "redux": {
+ "optional": true
+ }
+ }
+ },
"node_modules/react-router": {
"version": "5.3.4",
"license": "MIT",
@@ -21547,6 +22607,17 @@
"node": ">=8.10.0"
}
},
+ "node_modules/rechoir": {
+ "version": "0.6.2",
+ "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz",
+ "integrity": "sha512-HFM8rkZ+i3zrV+4LQjwQ0W+ez98pApMGM3HUrN04j3CqzPOzl9nmP15Y8YXNm8QHGv/eacOVEjqhmWpkRV0NAw==",
+ "dependencies": {
+ "resolve": "^1.1.6"
+ },
+ "engines": {
+ "node": ">= 0.10"
+ }
+ },
"node_modules/recma-build-jsx": {
"version": "1.0.0",
"license": "MIT",
@@ -21666,6 +22737,21 @@
"@docusaurus/utils": "^3.6.0"
}
},
+ "node_modules/redux": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz",
+ "integrity": "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==",
+ "license": "MIT"
+ },
+ "node_modules/redux-thunk": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/redux-thunk/-/redux-thunk-3.1.0.tgz",
+ "integrity": "sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw==",
+ "license": "MIT",
+ "peerDependencies": {
+ "redux": "^5.0.0"
+ }
+ },
"node_modules/reflect.getprototypeof": {
"version": "1.0.10",
"dev": true,
@@ -22099,7 +23185,9 @@
}
},
"node_modules/remark-gfm": {
- "version": "4.0.0",
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
+ "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==",
"license": "MIT",
"dependencies": {
"@types/mdast": "^4.0.0",
@@ -22308,6 +23396,12 @@
"resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
"integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ=="
},
+ "node_modules/reselect": {
+ "version": "5.1.1",
+ "resolved": "https://registry.npmjs.org/reselect/-/reselect-5.1.1.tgz",
+ "integrity": "sha512-K/BG6eIky/SBpzfHZv/dd+9JBFiS4SWV7FIujVyJRux6e45+73RaUHXLmIR1f7WOMaQ0U1km6qwklRQxpJJY0w==",
+ "license": "MIT"
+ },
"node_modules/resolve": {
"version": "1.22.11",
"resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.11.tgz",
@@ -22614,6 +23708,94 @@
"version": "2.1.2",
"license": "MIT"
},
+ "node_modules/sass": {
+ "version": "1.99.0",
+ "resolved": "https://registry.npmjs.org/sass/-/sass-1.99.0.tgz",
+ "integrity": "sha512-kgW13M54DUB7IsIRM5LvJkNlpH+WhMpooUcaWGFARkF1Tc82v9mIWkCbCYf+MBvpIUBSeSOTilpZjEPr2VYE6Q==",
+ "license": "MIT",
+ "dependencies": {
+ "chokidar": "^4.0.0",
+ "immutable": "^5.1.5",
+ "source-map-js": ">=0.6.2 <2.0.0"
+ },
+ "bin": {
+ "sass": "sass.js"
+ },
+ "engines": {
+ "node": ">=14.0.0"
+ },
+ "optionalDependencies": {
+ "@parcel/watcher": "^2.4.1"
+ }
+ },
+ "node_modules/sass-loader": {
+ "version": "16.0.7",
+ "resolved": "https://registry.npmjs.org/sass-loader/-/sass-loader-16.0.7.tgz",
+ "integrity": "sha512-w6q+fRHourZ+e+xA1kcsF27iGM6jdB8teexYCfdUw0sYgcDNeZESnDNT9sUmmPm3ooziwUJXGwZJSTF3kOdBfA==",
+ "license": "MIT",
+ "dependencies": {
+ "neo-async": "^2.6.2"
+ },
+ "engines": {
+ "node": ">= 18.12.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/webpack"
+ },
+ "peerDependencies": {
+ "@rspack/core": "0.x || ^1.0.0 || ^2.0.0-0",
+ "node-sass": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0",
+ "sass": "^1.3.0",
+ "sass-embedded": "*",
+ "webpack": "^5.0.0"
+ },
+ "peerDependenciesMeta": {
+ "@rspack/core": {
+ "optional": true
+ },
+ "node-sass": {
+ "optional": true
+ },
+ "sass": {
+ "optional": true
+ },
+ "sass-embedded": {
+ "optional": true
+ },
+ "webpack": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/sass/node_modules/chokidar": {
+ "version": "4.0.3",
+ "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+ "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+ "license": "MIT",
+ "dependencies": {
+ "readdirp": "^4.0.1"
+ },
+ "engines": {
+ "node": ">= 14.16.0"
+ },
+ "funding": {
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/sass/node_modules/readdirp": {
+ "version": "4.1.2",
+ "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+ "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 14.18.0"
+ },
+ "funding": {
+ "type": "individual",
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
"node_modules/sax": {
"version": "1.4.1",
"license": "ISC"
@@ -23064,6 +24246,23 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/shelljs": {
+ "version": "0.8.5",
+ "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.5.tgz",
+ "integrity": "sha512-TiwcRcrkhHvbrZbnRcFYMLl30Dfov3HKqzp5tO5b4pt6G/SezKcYhmDg15zXVBswHmctSAQKznqNW2LO5tTDow==",
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "glob": "^7.0.0",
+ "interpret": "^1.0.0",
+ "rechoir": "^0.6.2"
+ },
+ "bin": {
+ "shjs": "bin/shjs"
+ },
+ "engines": {
+ "node": ">=4"
+ }
+ },
"node_modules/should": {
"version": "13.2.3",
"resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz",
@@ -23871,6 +25070,37 @@
"resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.6.tgz",
"integrity": "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ=="
},
+ "node_modules/sucrase": {
+ "version": "3.35.1",
+ "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz",
+ "integrity": "sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==",
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/gen-mapping": "^0.3.2",
+ "commander": "^4.0.0",
+ "lines-and-columns": "^1.1.6",
+ "mz": "^2.7.0",
+ "pirates": "^4.0.1",
+ "tinyglobby": "^0.2.11",
+ "ts-interface-checker": "^0.1.9"
+ },
+ "bin": {
+ "sucrase": "bin/sucrase",
+ "sucrase-node": "bin/sucrase-node"
+ },
+ "engines": {
+ "node": ">=16 || 14 >=14.17"
+ }
+ },
+ "node_modules/sucrase/node_modules/commander": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz",
+ "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/supports-color": {
"version": "7.2.0",
"license": "MIT",
@@ -24313,6 +25543,27 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/thenify": {
+ "version": "3.3.1",
+ "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz",
+ "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==",
+ "license": "MIT",
+ "dependencies": {
+ "any-promise": "^1.0.0"
+ }
+ },
+ "node_modules/thenify-all": {
+ "version": "1.6.0",
+ "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz",
+ "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==",
+ "license": "MIT",
+ "dependencies": {
+ "thenify": ">= 3.1.0 < 4"
+ },
+ "engines": {
+ "node": ">=0.8"
+ }
+ },
"node_modules/thingies": {
"version": "2.5.0",
"resolved": "https://registry.npmjs.org/thingies/-/thingies-2.5.0.tgz",
@@ -24375,6 +25626,51 @@
"node": ">=18"
}
},
+ "node_modules/tinyglobby": {
+ "version": "0.2.16",
+ "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+ "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+ "license": "MIT",
+ "dependencies": {
+ "fdir": "^6.5.0",
+ "picomatch": "^4.0.4"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/SuperchupuDev"
+ }
+ },
+ "node_modules/tinyglobby/node_modules/fdir": {
+ "version": "6.5.0",
+ "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+ "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "peerDependencies": {
+ "picomatch": "^3 || ^4"
+ },
+ "peerDependenciesMeta": {
+ "picomatch": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/tinyglobby/node_modules/picomatch": {
+ "version": "4.0.4",
+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+ "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/jonschlinkert"
+ }
+ },
"node_modules/tinypool": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.0.tgz",
@@ -24524,6 +25820,12 @@
"node": ">=6.10"
}
},
+ "node_modules/ts-interface-checker": {
+ "version": "0.1.13",
+ "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz",
+ "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==",
+ "license": "Apache-2.0"
+ },
"node_modules/ts-node": {
"version": "10.9.1",
"dev": true,
@@ -25102,6 +26404,15 @@
"version": "1.4.1",
"license": "MIT"
},
+ "node_modules/use-editable": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/use-editable/-/use-editable-2.3.3.tgz",
+ "integrity": "sha512-7wVD2JbfAFJ3DK0vITvXBdpd9JAz5BcKAAolsnLBuBn6UDDwBGuCIAGvR3yA2BNKm578vAMVHFCWaOcA+BhhiA==",
+ "license": "MIT",
+ "peerDependencies": {
+ "react": ">= 16.8.0"
+ }
+ },
"node_modules/use-sync-external-store": {
"version": "1.5.0",
"resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.5.0.tgz",
@@ -26060,6 +27371,18 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/xml-formatter": {
+ "version": "3.7.0",
+ "resolved": "https://registry.npmjs.org/xml-formatter/-/xml-formatter-3.7.0.tgz",
+ "integrity": "sha512-+8qTc3zv2UcJ1v9IsSIce37Dl4MQG14Cp7tWrwmy202UaI1wqRukw5QMX1JHsV+DX64yw77EgGsj2s5wGvuMbQ==",
+ "license": "MIT",
+ "dependencies": {
+ "xml-parser-xo": "^4.1.5"
+ },
+ "engines": {
+ "node": ">= 16"
+ }
+ },
"node_modules/xml-js": {
"version": "1.6.11",
"resolved": "https://registry.npmjs.org/xml-js/-/xml-js-1.6.11.tgz",
@@ -26071,6 +27394,15 @@
"xml-js": "bin/cli.js"
}
},
+ "node_modules/xml-parser-xo": {
+ "version": "4.1.5",
+ "resolved": "https://registry.npmjs.org/xml-parser-xo/-/xml-parser-xo-4.1.5.tgz",
+ "integrity": "sha512-TxyRxk9sTOUg3glxSIY6f0nfuqRll2OEF8TspLgh5mZkLuBgheCn3zClcDSGJ58TvNmiwyCCuat4UajPud/5Og==",
+ "license": "MIT",
+ "engines": {
+ "node": ">= 16"
+ }
+ },
"node_modules/xtend": {
"version": "4.0.2",
"license": "MIT",
diff --git a/package.json b/package.json
index df509965dd..ce73bf04d0 100644
--- a/package.json
+++ b/package.json
@@ -52,6 +52,8 @@
"classnames": "2.5.1",
"clsx": "2.1.0",
"debug": "4.3.4",
+ "docusaurus-plugin-openapi-docs": "4.7.1",
+ "docusaurus-theme-openapi-docs": "4.7.1",
"file-loader": "6.2.0",
"json-loader": "0.5.7",
"json-schema-faker": "0.5.8",
diff --git a/src/sidebar.ts b/src/sidebar.ts
index 73aec49ab1..f55a41c1d9 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -5,6 +5,7 @@ import {
SidebarItem,
SidebarItemConfig,
} from "@docusaurus/plugin-content-docs/src/sidebars/types"
+import apiSidebar from "../docs/talos/reference/api/sidebar";
type SidebarItemsConfig = SidebarItemConfig[]
@@ -917,6 +918,130 @@ const keto: SidebarItemsConfig = [
},
]
+const talos: SidebarItemsConfig = [
+ {
+ type: "doc",
+ id: "talos/index",
+ label: "Home",
+ },
+ {
+ type: "category",
+ label: "Quickstart",
+ collapsed: false,
+ link: { type: "doc", id: "talos/quickstart/index" },
+ items: ["talos/quickstart/docker-commercial"],
+ },
+ {
+ type: "category",
+ label: "talos/integrate",
+ collapsed: false,
+ link: { type: "doc", id: "talos/integrate/index" },
+ items: [
+ "talos/integrate/issue-and-verify",
+ "talos/integrate/import-keys",
+ "talos/integrate/derive-tokens",
+ "talos/integrate/batch-operations",
+ "talos/integrate/key-lifecycle",
+ "talos/integrate/self-revocation",
+ "talos/integrate/ip-restrictions",
+ "talos/integrate/rate-limiting",
+ "talos/integrate/error-handling",
+ {
+ type: "category",
+ label: "SDK",
+ items: ["talos/integrate/sdk/go", "talos/integrate/sdk/curl"],
+ },
+ ],
+ },
+ {
+ type: "category",
+ label: "talos/operate",
+ collapsed: false,
+ link: { type: "doc", id: "talos/operate/index" },
+ items: [
+ "talos/operate/install",
+ "talos/operate/configure",
+ {
+ type: "category",
+ label: "Database",
+ link: { type: "doc", id: "talos/operate/database/index" },
+ items: [
+ "talos/operate/database/sqlite",
+ "talos/operate/database/postgresql",
+ "talos/operate/database/mysql",
+ "talos/operate/database/cockroachdb",
+ "talos/operate/database/migrations",
+ ],
+ },
+ {
+ type: "category",
+ label: "Deploy",
+ link: { type: "doc", id: "talos/operate/deploy/index" },
+ items: [
+ "talos/operate/deploy/docker",
+ "talos/operate/deploy/kubernetes",
+ "talos/operate/deploy/separate-planes",
+ "talos/operate/deploy/edge-proxy",
+ ],
+ },
+ "talos/operate/secrets",
+ "talos/operate/tls",
+ {
+ type: "category",
+ label: "Monitoring",
+ link: { type: "doc", id: "talos/operate/monitoring/index" },
+ items: [
+ "talos/operate/monitoring/metrics",
+ "talos/operate/monitoring/tracing",
+ "talos/operate/monitoring/health-checks",
+ ],
+ },
+ {
+ type: "category",
+ label: "Cache",
+ link: { type: "doc", id: "talos/operate/cache/index" },
+ items: ["talos/operate/cache/memory", "talos/operate/cache/redis"],
+ },
+ "talos/operate/multi-tenancy",
+ "talos/operate/troubleshooting",
+ "talos/operate/security-hardening",
+ ],
+ },
+ {
+ type: "category",
+ label: "Concepts",
+ collapsed: true,
+ link: { type: "doc", id: "talos/concepts/index" },
+ items: [
+ "talos/concepts/architecture",
+ "talos/concepts/credential-types",
+ "talos/concepts/token-format",
+ "talos/concepts/security-model",
+ "talos/concepts/ip-restrictions",
+ "talos/concepts/caching",
+ "talos/concepts/rate-limiting",
+ "talos/concepts/token-derivation-security",
+ ],
+ },
+ {
+ type: "category",
+ label: "Reference",
+ collapsed: true,
+ link: { type: "doc", id: "talos/reference/index" },
+ items: [
+ {
+ type: "category",
+ label: "API",
+ link: { type: "doc", id: "talos/reference/api/ory-talos-api" },
+ items: apiSidebar,
+ },
+ "talos/reference/config",
+ "talos/reference/error-codes",
+ "talos/reference/token-format",
+ ],
+ },
+ ]
+
const polis: SidebarItemsConfig = [
homeLink,
"polis/index",
@@ -1346,6 +1471,7 @@ module.exports = {
polis,
oathkeeper,
api,
+ talos,
polisApi,
sdk,
cli,
From d181023fe09ba2728d58b7f1a388d4217d963478 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:58:25 +0200
Subject: [PATCH 2/8] fix: wire up openapi-docs plugin for talos API reference
The talos `.api.mdx` pages import `MethodEndpoint` and related components
from `docusaurus-theme-openapi-docs`, which read from a Redux store that
is only provisioned when `docusaurus-plugin-openapi-docs` is registered
and `docItemComponent: "@theme/ApiItem"` is set on the content-docs
plugin. Without those, SSR failed with
`Cannot destructure property 'store' of 'i' as it is null` on every
talos API route, breaking `test-build` and the Vercel preview deploy.
Register the plugin with a `talos` config pointing at the committed
OpenAPI spec, set `docItemComponent: "@theme/ApiItem"`, and apply
prettier to the talos docs that had drifted from the project style.
Co-Authored-By: Claude Opus 4.7
---
docs/talos/CLAUDE.md | 32 +-
docs/talos/concepts/architecture.md | 50 +-
docs/talos/concepts/caching.md | 8 +-
docs/talos/concepts/credential-types.md | 25 +-
docs/talos/concepts/index.md | 3 +-
docs/talos/concepts/ip-restrictions.md | 73 +-
docs/talos/concepts/rate-limiting.md | 86 +-
docs/talos/concepts/security-model.md | 79 +-
.../concepts/token-derivation-security.md | 66 +-
docs/talos/concepts/token-format.md | 7 +-
docs/talos/index.md | 36 +-
docs/talos/integrate/batch-operations.md | 21 +-
docs/talos/integrate/derive-tokens.md | 25 +-
docs/talos/integrate/error-handling.md | 23 +-
docs/talos/integrate/import-keys.md | 34 +-
docs/talos/integrate/index.md | 20 +-
docs/talos/integrate/ip-restrictions.md | 32 +-
docs/talos/integrate/issue-and-verify.md | 39 +-
docs/talos/integrate/key-lifecycle.md | 33 +-
docs/talos/integrate/rate-limiting.md | 75 +-
docs/talos/integrate/sdk/go.md | 21 +-
docs/talos/integrate/self-revocation.md | 17 +-
docs/talos/operate/benchmarks.md | 31 +-
docs/talos/operate/cache/index.md | 8 +-
docs/talos/operate/cache/memory.md | 8 +-
docs/talos/operate/cache/redis.md | 5 +-
docs/talos/operate/configure.md | 12 +-
docs/talos/operate/database/cockroachdb.md | 27 +-
docs/talos/operate/database/index.md | 3 +-
docs/talos/operate/database/mysql.md | 20 +-
docs/talos/operate/database/postgresql.md | 28 +-
docs/talos/operate/deploy/edge-proxy.md | 48 +-
docs/talos/operate/deploy/separate-planes.md | 22 +-
docs/talos/operate/index.md | 12 +-
docs/talos/operate/install.md | 3 +-
.../talos/operate/monitoring/health-checks.md | 4 +-
docs/talos/operate/monitoring/index.md | 3 +-
docs/talos/operate/monitoring/tracing.md | 5 +-
docs/talos/operate/multi-tenancy.md | 16 +-
docs/talos/operate/secrets.md | 4 +-
docs/talos/operate/security-hardening.md | 14 +-
docs/talos/operate/tls.md | 3 +-
docs/talos/operate/troubleshooting.md | 10 +-
docs/talos/quickstart/docker-commercial.md | 3 +-
docs/talos/quickstart/index.md | 18 +-
docs/talos/reference/api.json | 1631 +++++++++++++++++
...e-batch-import-api-keys.RequestSchema.json | 103 +-
...ice-batch-import-api-keys.StatusCodes.json | 190 +-
...lane-service-batch-import-api-keys.api.mdx | 34 +-
...delete-imported-api-key.ParamsDetails.json | 12 +-
...delete-imported-api-key.RequestSchema.json | 2 +-
...e-delete-imported-api-key.StatusCodes.json | 37 +-
...ne-service-delete-imported-api-key.api.mdx | 38 +-
...ne-service-derive-token.RequestSchema.json | 36 +-
...lane-service-derive-token.StatusCodes.json | 52 +-
.../admin-plane-service-derive-token.api.mdx | 30 +-
...ce-get-imported-api-key.ParamsDetails.json | 12 +-
...ce-get-imported-api-key.RequestSchema.json | 2 +-
...vice-get-imported-api-key.StatusCodes.json | 130 +-
...plane-service-get-imported-api-key.api.mdx | 37 +-
...vice-get-issued-api-key.ParamsDetails.json | 11 +-
...vice-get-issued-api-key.RequestSchema.json | 2 +-
...ervice-get-issued-api-key.StatusCodes.json | 123 +-
...n-plane-service-get-issued-api-key.api.mdx | 38 +-
...-plane-service-get-jwks.RequestSchema.json | 2 +-
...in-plane-service-get-jwks.StatusCodes.json | 43 +-
.../api/admin-plane-service-get-jwks.api.mdx | 27 +-
...-service-import-api-key.RequestSchema.json | 92 +-
...ne-service-import-api-key.StatusCodes.json | 140 +-
...admin-plane-service-import-api-key.api.mdx | 31 +-
...e-service-issue-api-key.RequestSchema.json | 70 +-
...ane-service-issue-api-key.StatusCodes.json | 137 +-
.../admin-plane-service-issue-api-key.api.mdx | 30 +-
...-list-imported-api-keys.ParamsDetails.json | 23 +-
...-list-imported-api-keys.RequestSchema.json | 2 +-
...ce-list-imported-api-keys.StatusCodes.json | 150 +-
...ane-service-list-imported-api-keys.api.mdx | 38 +-
...ce-list-issued-api-keys.ParamsDetails.json | 23 +-
...ce-list-issued-api-keys.RequestSchema.json | 2 +-
...vice-list-issued-api-keys.StatusCodes.json | 139 +-
...plane-service-list-issued-api-keys.api.mdx | 38 +-
...-service-revoke-api-key.ParamsDetails.json | 11 +-
...-service-revoke-api-key.RequestSchema.json | 35 +-
...ne-service-revoke-api-key.StatusCodes.json | 37 +-
...admin-plane-service-revoke-api-key.api.mdx | 34 +-
...e-rotate-issued-api-key.ParamsDetails.json | 12 +-
...e-rotate-issued-api-key.RequestSchema.json | 78 +-
...ice-rotate-issued-api-key.StatusCodes.json | 224 ++-
...lane-service-rotate-issued-api-key.api.mdx | 39 +-
...e-update-issued-api-key.ParamsDetails.json | 11 +-
...e-update-issued-api-key.RequestSchema.json | 54 +-
...ice-update-issued-api-key.StatusCodes.json | 123 +-
...lane-service-update-issued-api-key.api.mdx | 38 +-
...e-batch-verify-api-keys.RequestSchema.json | 31 +-
...ice-batch-verify-api-keys.StatusCodes.json | 122 +-
...lane-service-batch-verify-api-keys.api.mdx | 34 +-
...ice-self-revoke-api-key.RequestSchema.json | 37 +-
...rvice-self-revoke-api-key.StatusCodes.json | 41 +-
...-plane-service-self-revoke-api-key.api.mdx | 35 +-
...-service-verify-api-key.RequestSchema.json | 22 +-
...ne-service-verify-api-key.StatusCodes.json | 110 +-
.../data-plane-service-verify-api-key.api.mdx | 34 +-
.../reference/api/ory-talos-api.info.mdx | 27 +-
docs/talos/reference/api/sidebar.ts | 6 +-
.../reference/cli/talos-jwk-generate-ecdsa.md | 4 +-
.../reference/cli/talos-jwk-generate-hmac.md | 4 +-
docs/talos/reference/cli/talos-jwk.md | 4 +-
.../reference/cli/talos-keys-derive-token.md | 3 +-
.../cli/talos-keys-imported-batch-import.md | 3 +-
.../reference/cli/talos-keys-imported.md | 3 +-
docs/talos/reference/cli/talos-keys-issued.md | 3 +-
.../reference/cli/talos-keys-self-revoke.md | 3 +-
docs/talos/reference/cli/talos-keys-verify.md | 3 +-
docs/talos/reference/cli/talos-keys.md | 9 +-
.../talos/reference/cli/talos-migrate-down.md | 3 +-
.../reference/cli/talos-migrate-force.md | 3 +-
docs/talos/reference/cli/talos-serve-admin.md | 4 +-
docs/talos/reference/cli/talos-serve-check.md | 4 +-
docs/talos/reference/cli/talos.md | 4 +-
docs/talos/reference/config.md | 14 +-
docs/talos/reference/error-codes.md | 8 +-
docs/talos/reference/events.md | 17 +-
docs/talos/reference/token-format.md | 20 +-
docusaurus.config.ts | 16 +
src/sidebar.ts | 248 +--
125 files changed, 4959 insertions(+), 1235 deletions(-)
create mode 100644 docs/talos/reference/api.json
diff --git a/docs/talos/CLAUDE.md b/docs/talos/CLAUDE.md
index 508f82ad40..96b425ab9d 100644
--- a/docs/talos/CLAUDE.md
+++ b/docs/talos/CLAUDE.md
@@ -5,11 +5,10 @@
Use `jq` instead of `python3` for all JSON operations in code examples:
- **Pretty-print:** `| jq .` not `| python3 -m json.tool`
-- **Extract fields:** `| jq -r '.field'` not
- `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
+- **Extract fields:** `| jq -r '.field'` not `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
-**Never write curl output to temporary files.** Capture responses in shell variables instead.
-File-based operations fail when `/tmp` doesn't exist or isn't writable.
+**Never write curl output to temporary files.** Capture responses in shell variables instead. File-based operations fail when
+`/tmp` doesn't exist or isn't writable.
```bash
# Good: variable-based
@@ -28,8 +27,8 @@ rm -f /tmp/response.json
## API Field Documentation
-Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or
-enum tables. These are maintained in the canonical references:
+Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or enum tables. These are maintained
+in the canonical references:
- **Field tables** -> auto-generated API reference at `reference/api/*.api.mdx`
- **Error codes** -> `reference/error-codes.md`
@@ -37,10 +36,9 @@ enum tables. These are maintained in the canonical references:
### What belongs in integration guides
- **Workflow and examples**: curl commands, step-by-step instructions, the "how" and "why"
-- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The
- response includes a `secret` field -- store it securely")
-- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT
- vs macaroon)
+- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The response includes a `secret` field
+ -- store it securely")
+- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT vs macaroon)
- **Operational constraints**: limits, cache control headers, retry strategies
- **Links to reference**: always link to the canonical source for complete field/error details
@@ -53,9 +51,8 @@ enum tables. These are maintained in the canonical references:
### Link format
-**All links MUST be relative links to markdown/mdx files with the file extension.** Never use
-absolute links (starting with `/`) or links without a file extension. Hashbang anchors are allowed
-after the file extension.
+**All links MUST be relative links to markdown/mdx files with the file extension.** Never use absolute links (starting with `/`)
+or links without a file extension. Hashbang anchors are allowed after the file extension.
- Links to `.md` files: `[text](../reference/error-codes.md#section)`
- Links to `.api.mdx` files: `[text](../reference/api/admin-plane-service-issue-api-key.api.mdx)`
@@ -88,13 +85,11 @@ Ensure that notes / callouts have two line breaks, or they will get formatted in
**Incorrect:**
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by
-external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
```
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by
-external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
```
Correct:
@@ -102,8 +97,7 @@ Correct:
```md
:::note
-Internal package The Go client is in an `internal/` package and cannot be imported by external Go
-modules.
+Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules.
:::
```
diff --git a/docs/talos/concepts/architecture.md b/docs/talos/concepts/architecture.md
index 8084b4ee50..f82fc1f563 100644
--- a/docs/talos/concepts/architecture.md
+++ b/docs/talos/concepts/architecture.md
@@ -8,15 +8,15 @@ Talos separates API key management into two planes.
## Admin plane
-The admin plane handles all write operations: key issuance, rotation, revocation, token derivation,
-and JWKS. It is typically exposed only to internal services.
+The admin plane handles all write operations: key issuance, rotation, revocation, token derivation, and JWKS. It is typically
+exposed only to internal services.
Endpoints: `/v2/admin/`
## Data plane
-The data plane handles high-throughput read operations: key verification, batch verification, and
-self-revocation. It is designed for low-latency edge deployment.
+The data plane handles high-throughput read operations: key verification, batch verification, and self-revocation. It is designed
+for low-latency edge deployment.
Endpoints: `/v2/admin/apiKeys:verify`, `/v2/admin/apiKeys:batchVerify`, `/v2/apiKeys:selfRevoke`
@@ -43,8 +43,7 @@ Client --> Data Plane --> Cache (hit?) --> Database --> Response
| Split planes | Commercial | Admin and data planes as separate deployments |
| Edge proxy | Commercial | Data plane at the edge with local cache |
-Both planes share the same database. The data plane can use caching (memory or Redis) to minimize
-database load.
+Both planes share the same database. The data plane can use caching (memory or Redis) to minimize database load.
## Ports
@@ -64,9 +63,8 @@ The system is divided into distinct layers:
- **Persistence layer**: Database abstraction with pluggable drivers
- **Cache layer**: Performance optimization with multiple backends
-This separation allows independent scaling of components, different SLOs for different operations
-(admin targets \<100ms p99, data plane targets \<3ms p99), and clear boundaries between
-responsibilities.
+This separation allows independent scaling of components, different SLOs for different operations (admin targets \<100ms p99, data
+plane targets \<3ms p99), and clear boundaries between responsibilities.
### Production-first design
@@ -80,8 +78,7 @@ Inspired by proven systems like SpiceDB and Kubernetes:
### Performance by default
- Self-contained tokens (JWT/macaroon) enable stateless verification
-- HMAC-SHA256 for fast revocation checks -- not bcrypt, which would limit throughput to ~10 req/sec
- per core
+- HMAC-SHA256 for fast revocation checks -- not bcrypt, which would limit throughput to ~10 req/sec per core
- LRU caching for hot paths
- Minimal allocations in the verification path
@@ -128,21 +125,21 @@ Clients (CLI, SDK, HTTP)
+-----------+ +-----------+
```
-All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through
-middleware for logging, metrics, and tracing before being routed to the appropriate plane.
+All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through middleware for logging,
+metrics, and tracing before being routed to the appropriate plane.
## Component overview
### HTTP server
-The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both
-planes through a single port, handles CORS and compression, and exposes OpenAPI documentation.
+The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both planes through a single port,
+handles CORS and compression, and exposes OpenAPI documentation.
### Service layer
-Business logic is split between the admin plane service (key lifecycle, import, token derivation,
-input validation) and the data plane verifier (token parsing, signature verification, revocation
-checking, cache management). The verifier is optimized for the hot path with minimal allocations.
+Business logic is split between the admin plane service (key lifecycle, import, token derivation, input validation) and the data
+plane verifier (token parsing, signature verification, revocation checking, cache management). The verifier is optimized for the
+hot path with minimal allocations.
### Persistence
@@ -175,18 +172,15 @@ Talos supports multiple signing algorithms:
Built-in instrumentation across three pillars:
-- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate
- counters
-- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and
- Jaeger exporters
+- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate counters
+- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and Jaeger exporters
- **Logging** -- structured JSON logging via slog with correlation IDs and contextual fields
## Scalability
### Small (\<1k RPS)
-A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external
-dependencies required.
+A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external dependencies required.
- OSS edition sufficient
- 1 CPU, 512MB RAM
@@ -194,8 +188,8 @@ dependencies required.
### Medium (10-50k RPS)
-Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for
-durability. Redis provides shared caching across data plane instances.
+Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for durability. Redis provides shared
+caching across data plane instances.
- Commercial edition
- Auto-scaling for data plane
@@ -203,8 +197,8 @@ durability. Redis provides shared caching across data plane instances.
### Large (200k+ RPS)
-A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis
-cache and PostgreSQL with read replicas and connection pooling. Supports multi-region deployment.
+A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis cache and PostgreSQL with read
+replicas and connection pooling. Supports multi-region deployment.
- Commercial edition
- Regional data plane deployment
diff --git a/docs/talos/concepts/caching.md b/docs/talos/concepts/caching.md
index 0e59a84cad..707688901f 100644
--- a/docs/talos/concepts/caching.md
+++ b/docs/talos/concepts/caching.md
@@ -8,8 +8,8 @@ Talos can cache verification results to reduce database load and improve latency
## How it works
-When caching is enabled, the first verification request for a key hits the database. Subsequent
-requests within the cache TTL are served from cache without a database lookup.
+When caching is enabled, the first verification request for a key hits the database. Subsequent requests within the cache TTL are
+served from cache without a database lookup.
## Cache types
@@ -38,8 +38,8 @@ curl -X POST http://localhost:4420/v2/admin/apiKeys:verify \
-d '{"credential": "..."}'
```
-See the [quickstart revocation check](../quickstart/index.md) and the
-[curl SDK reference](../integrate/sdk/curl.md) for tested examples using cache bypass.
+See the [quickstart revocation check](../quickstart/index.md) and the [curl SDK reference](../integrate/sdk/curl.md) for tested
+examples using cache bypass.
## TTL guidelines
diff --git a/docs/talos/concepts/credential-types.md b/docs/talos/concepts/credential-types.md
index 4e33952250..813849a668 100644
--- a/docs/talos/concepts/credential-types.md
+++ b/docs/talos/concepts/credential-types.md
@@ -8,35 +8,30 @@ Talos manages four credential types.
## Issued API keys
-Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable
-TTL. The key ID (UUID) is embedded in the token for direct database lookup. The full secret is
-returned once at creation.
+Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable TTL. The key ID (UUID) is
+embedded in the token for direct database lookup. The full secret is returned once at creation.
**Lifecycle**: Issue, rotate, update metadata, revoke.
## Imported API keys
External credentials (Stripe, GitHub, etc.) stored by hash. Any string format accepted. Talos stores
-`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and
-scopes as issued keys.
+`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and scopes as issued keys.
**Lifecycle**: Import, update metadata, revoke, delete.
## Derived JWTs
-Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg`
-field in the JWK (EdDSA or RS256). Can be verified independently using the JWKS endpoint
-(`GET /v2/admin/derivedKeys/jwks.json`). Claims include `key_id`, `actor_id`, scopes, and
-expiration.
+Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg` field in the JWK (EdDSA or
+RS256). Can be verified independently using the JWKS endpoint (`GET /v2/admin/derivedKeys/jwks.json`). Claims include `key_id`,
+`actor_id`, scopes, and expiration.
## Derived macaroons
-Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and
-contextual attenuation.
+Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and contextual attenuation.
## Credential routing
-When a credential is submitted to `/v2/admin/apiKeys:verify`, Talos identifies the type
-automatically by its format and routes it to the appropriate verification handler. See the
-[credential routing table](../reference/token-format.md#credential-routing) for the full
-format-to-type mapping and lookup methods.
+When a credential is submitted to `/v2/admin/apiKeys:verify`, Talos identifies the type automatically by its format and routes it
+to the appropriate verification handler. See the [credential routing table](../reference/token-format.md#credential-routing) for
+the full format-to-type mapping and lookup methods.
diff --git a/docs/talos/concepts/index.md b/docs/talos/concepts/index.md
index 6b57a7b962..6ae6bef95b 100644
--- a/docs/talos/concepts/index.md
+++ b/docs/talos/concepts/index.md
@@ -11,7 +11,6 @@ Core ideas behind Ory Talos.
- [Token format](token-format.md) — v1 key format specification
- [Security model](security-model.md) — cryptographic primitives and tenant isolation
- [Caching and consistency](caching.md) — verification caching and revocation propagation
-- [Token derivation security](token-derivation-security.md) — stateless verification and revocation
- semantics
+- [Token derivation security](token-derivation-security.md) — stateless verification and revocation semantics
- [Rate limiting](rate-limiting.md) — rate limit metadata on API keys
- [IP restrictions](ip-restrictions.md) — CIDR-based access control for API keys
diff --git a/docs/talos/concepts/ip-restrictions.md b/docs/talos/concepts/ip-restrictions.md
index 6278eaf2a7..dce06df1d9 100644
--- a/docs/talos/concepts/ip-restrictions.md
+++ b/docs/talos/concepts/ip-restrictions.md
@@ -5,10 +5,9 @@ description: CIDR-based allowlists that restrict which client IPs can use an API
# IP restrictions
-Talos supports per-key IP restrictions that limit which client IP addresses can use an API key.
-Restrictions are defined as a list of CIDR ranges (for example, `192.168.1.0/24` or
-`2001:db8::/32`). Only requests originating from an IP within the allowlist are accepted. Keys
-without IP restrictions accept traffic from any address.
+Talos supports per-key IP restrictions that limit which client IP addresses can use an API key. Restrictions are defined as a list
+of CIDR ranges (for example, `192.168.1.0/24` or `2001:db8::/32`). Only requests originating from an IP within the allowlist are
+accepted. Keys without IP restrictions accept traffic from any address.
## How IP restrictions work
@@ -16,9 +15,9 @@ IP restriction enforcement has two stages: **IP resolution** and **CIDR matching
### IP resolution
-When a verification request arrives, Talos captures all IP-related headers from the HTTP request
-into context through middleware. At verification time, the configured **client IP source**
-determines which header to use for extracting the client address. The available sources are:
+When a verification request arrives, Talos captures all IP-related headers from the HTTP request into context through middleware.
+At verification time, the configured **client IP source** determines which header to use for extracting the client address. The
+available sources are:
| Source | Header / value used | Typical use case |
| ------------------ | ---------------------------- | -------------------------------------- |
@@ -28,33 +27,32 @@ determines which header to use for extracting the client address. The available
| `X_REAL_IP` | `X-Real-Ip` | Behind NGINX with `proxy_set_header` |
| `TRUE_CLIENT_IP` | `True-Client-Ip` | Behind Akamai or Cloudflare Enterprise |
-If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is
-set once at startup and applies to all verification requests.
+If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is set once at startup and
+applies to all verification requests.
### CIDR matching
-After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP
-falls within any of the ranges. Both IPv4 and IPv6 CIDR notation are supported (for example,
-`10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32` (IPv4) or `/128` (IPv6) range.
+After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP falls within any of the ranges.
+Both IPv4 and IPv6 CIDR notation are supported (for example, `10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32`
+(IPv4) or `/128` (IPv6) range.
-If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification
-fails with error code `VERIFICATION_ERROR_IP_NOT_ALLOWED`.
+If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification fails with error code
+`VERIFICATION_ERROR_IP_NOT_ALLOWED`.
## Fail-closed behavior
-IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for
-example, because the request context does not contain IP metadata -- the verification request is
-denied. This prevents accidental access when header forwarding is misconfigured.
+IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for example, because the request context
+does not contain IP metadata -- the verification request is denied. This prevents accidental access when header forwarding is
+misconfigured.
-This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking
-legitimate traffic during limiter outages.
+This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking legitimate traffic during limiter
+outages.
## Cache interaction
-Cached verification results still contain the key's allowed CIDR list. When a cached key is
-returned, Talos re-evaluates the IP restriction against the **current request's** client IP before
-returning a success response. This means IP restrictions are enforced on every request, regardless
-of whether the result came from cache or the database.
+Cached verification results still contain the key's allowed CIDR list. When a cached key is returned, Talos re-evaluates the IP
+restriction against the **current request's** client IP before returning a success response. This means IP restrictions are
+enforced on every request, regardless of whether the result came from cache or the database.
The enforcement sequence is:
@@ -66,29 +64,24 @@ The enforcement sequence is:
## IPv4 and IPv6 support
-IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same
-allowlist. Talos parses client addresses using Go's `net.ParseIP`, which handles both formats
-transparently. There is no implicit mapping between IPv4 and IPv6 -- a `10.0.0.0/8` range does not
-match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
+IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same allowlist. Talos parses client
+addresses using Go's `net.ParseIP`, which handles both formats transparently. There is no implicit mapping between IPv4 and IPv6
+-- a `10.0.0.0/8` range does not match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
## Key concepts
-- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is
- denied. Keys without restrictions accept all IPs.
+- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is denied. Keys without
+ restrictions accept all IPs.
- **Per-key granularity** -- each key has its own CIDR list. Keys do not share IP restrictions.
-- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured
- proxies cannot bypass restrictions.
-- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32`
- (IPv4) or `/128` (IPv6).
-- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside
- the key's allowed ranges. See the
- [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is
- served from cache.
+- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured proxies cannot bypass restrictions.
+- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32` (IPv4) or `/128` (IPv6).
+- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside the key's allowed ranges. See
+ the [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
+- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is served from cache.
## Next steps
- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
- [Configuration reference](../reference/config.md) -- client IP source and related settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
- error codes including `VERIFICATION_ERROR_IP_NOT_ALLOWED`
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
+ `VERIFICATION_ERROR_IP_NOT_ALLOWED`
diff --git a/docs/talos/concepts/rate-limiting.md b/docs/talos/concepts/rate-limiting.md
index 76ce2a560a..d411347253 100644
--- a/docs/talos/concepts/rate-limiting.md
+++ b/docs/talos/concepts/rate-limiting.md
@@ -1,38 +1,33 @@
---
title: Rate limiting
-description:
- Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
+description: Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
---
# Rate limiting
-Talos supports per-key rate limit policies that control how many requests a key can make within a
-time window. A rate limit policy consists of two fields: a **quota** (maximum request count) and a
-**window** (time period in seconds). Keys without a policy are never rate limited.
+Talos supports per-key rate limit policies that control how many requests a key can make within a time window. A rate limit policy
+consists of two fields: a **quota** (maximum request count) and a **window** (time period in seconds). Keys without a policy are
+never rate limited.
How enforcement works depends on your edition.
## OSS edition: metadata and headers
-In the OSS edition, Talos stores rate limit policies on keys and returns them in verification
-responses. It does not enforce limits itself. Your API gateway or reverse proxy reads the policy
-from the response headers and applies enforcement externally.
+In the OSS edition, Talos stores rate limit policies on keys and returns them in verification responses. It does not enforce
+limits itself. Your API gateway or reverse proxy reads the policy from the response headers and applies enforcement externally.
-This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy,
-NGINX, Kong, or a dedicated service). Verification responses include IETF-format headers that
-gateways can consume directly:
+This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy, NGINX, Kong, or a dedicated
+service). Verification responses include IETF-format headers that gateways can consume directly:
- **`RateLimit-Policy`** -- declares the key's quota and window (e.g., `"default";q=100;w=60`).
- **`RateLimit`** -- reports remaining quota (e.g., `"default";r=42`).
## Commercial edition: server-side enforcement
-The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the
-verification response returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`.
-The HTTP status remains **200** because the verification endpoint always returns a structured
-response — the rate limit status is conveyed through the response body, not the HTTP status code.
-This design allows gateways to distinguish transport errors from application-level rate limiting
-decisions.
+The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the verification response returns
+`is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`. The HTTP status remains **200** because the verification
+endpoint always returns a structured response — the rate limit status is conveyed through the response body, not the HTTP status
+code. This design allows gateways to distinguish transport errors from application-level rate limiting decisions.
### Backends
@@ -43,15 +38,15 @@ The commercial edition supports two enforcement backends:
| `memory` | GCRA | Single process (not shared) | Lost on restart |
| `redis` | GCRA | Shared across all connected pods | Survives restarts |
-Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate
-limiting without the boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp
-per key and allows requests as long as the average rate stays within the configured quota.
+Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate limiting without the
+boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp per key and allows requests as long as the average
+rate stays within the configured quota.
-**Memory** is suited for single-node deployments or development. Each process maintains independent
-counters per key, so state is not shared across pods.
+**Memory** is suited for single-node deployments or development. Each process maintains independent counters per key, so state is
+not shared across pods.
-**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the
-same Redis instance. State survives process restarts as long as Redis is available.
+**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the same Redis instance. State
+survives process restarts as long as Redis is available.
### Configuration
@@ -61,16 +56,14 @@ rate_limit:
backend: memory # Requires restart: changes the backend type
```
-- **`rate_limit.enabled`** is checked on every verification request through the config provider. You
- can toggle it at runtime by editing the config file -- Talos picks up the change automatically.
-- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this
- value requires a restart because it initializes different infrastructure (in-memory maps vs. Redis
- connections).
+- **`rate_limit.enabled`** is checked on every verification request through the config provider. You can toggle it at runtime by
+ editing the config file -- Talos picks up the change automatically.
+- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this value requires a restart because
+ it initializes different infrastructure (in-memory maps vs. Redis connections).
## HTTP response headers
-When a key has a rate limit policy, verification responses include IETF draft-compliant headers
-regardless of edition:
+When a key has a rate limit policy, verification responses include IETF draft-compliant headers regardless of edition:
| Header | Description | Example |
| ------------------ | --------------------------------------------------- | ---------------------- |
@@ -78,32 +71,29 @@ regardless of edition:
| `RateLimit` | Reports remaining quota | `"default";r=42` |
| `Retry-After` | Seconds to wait before retrying (only when limited) | `18` |
-Gateways and clients can use these headers for both external enforcement (OSS) and client-side
-backoff (Commercial).
+Gateways and clients can use these headers for both external enforcement (OSS) and client-side backoff (Commercial).
## Fail-open behavior
-If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos
-**fails open**: verification succeeds but rate limit metadata is omitted from the response. This
-design prevents limiter outages from blocking legitimate traffic.
+If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos **fails open**: verification
+succeeds but rate limit metadata is omitted from the response. This design prevents limiter outages from blocking legitimate
+traffic.
## Key concepts
- **Per-key isolation** -- each key has its own counter. Keys do not share rate limit budgets.
-- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g.
- `"60s"`). Both must be set for enforcement to apply.
-- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate
- limiting.
-- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota
- (Commercial only). See the
+- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g. `"60s"`). Both must be set for
+ enforcement to apply.
+- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate limiting.
+- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota (Commercial only). See the
[error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification
- result that is still valid will be returned without consulting the rate limiter.
+- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification result that is still valid will
+ be returned without consulting the rate limiter.
## Next steps
-- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify
- rate-limited keys, and handle quota exhaustion
+- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify rate-limited keys, and handle quota
+ exhaustion
- [Configuration reference](../reference/config.md) -- all `rate_limit.*` settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
- error codes including `VERIFICATION_ERROR_RATE_LIMITED`
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
+ `VERIFICATION_ERROR_RATE_LIMITED`
diff --git a/docs/talos/concepts/security-model.md b/docs/talos/concepts/security-model.md
index 94b44e6813..b65d624ec4 100644
--- a/docs/talos/concepts/security-model.md
+++ b/docs/talos/concepts/security-model.md
@@ -15,8 +15,8 @@ title: Security model
## Secret rotation
-Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the old
-one to `retired`. During verification, all secrets are tried in order.
+Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the old one to `retired`. During
+verification, all secrets are tried in order.
## Tenant isolation
@@ -24,14 +24,12 @@ Multi-tenant deployments use Network IDs (NID) for data isolation:
- **Database**: Composite primary keys `(nid, key_id)` prevent cross-tenant access
- **Token claims**: NID is embedded in derived tokens and validated during verification
-- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different
- hashes per tenant
+- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different hashes per tenant
## Cache security
-Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis
-keys, or memory cache entries. This prevents credential leakage through cache inspection, Redis
-`MONITOR` commands, or memory dumps.
+Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis keys, or memory cache entries.
+This prevents credential leakage through cache inspection, Redis `MONITOR` commands, or memory dumps.
- **Cache key format:** `namespace:nid:sha256(credential)` -- deterministic, no plaintext
- **Reverse index:** Stores `key_id → sha256(credential)` for invalidation lookups -- no raw secrets
@@ -39,28 +37,25 @@ keys, or memory cache entries. This prevents credential leakage through cache in
## Admin/data plane separation
-The admin plane (key management) and data plane (verification) can be deployed separately. The admin
-plane should be restricted to internal networks. The data plane can be exposed publicly.
+The admin plane (key management) and data plane (verification) can be deployed separately. The admin plane should be restricted to
+internal networks. The data plane can be exposed publicly.
## Key lifecycle
-Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is
-irreversible. Expired keys are rejected during verification.
+Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is irreversible. Expired keys are rejected
+during verification.
## Why HMAC over bcrypt
-Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen
-passwords with ~40-60 bits of entropy). They use intentional slowness (~100ms per hash) to make
-brute-force attacks against weak passwords expensive.
+Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen passwords with ~40-60 bits of
+entropy). They use intentional slowness (~100ms per hash) to make brute-force attacks against weak passwords expensive.
-API keys are fundamentally different. They are **cryptographically random** with 128+ bits of
-entropy, making dictionary attacks impossible. The key space of 2^128 (340 undecillion combinations)
-renders brute force infeasible regardless of hashing speed.
+API keys are fundamentally different. They are **cryptographically random** with 128+ bits of entropy, making dictionary attacks
+impossible. The key space of 2^128 (340 undecillion combinations) renders brute force infeasible regardless of hashing speed.
-HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the
-database. A database breach alone is insufficient to verify candidate keys -- the attacker must also
-compromise the secret. This provides a stronger security boundary than bcrypt, which stores
-everything needed for verification in the database itself.
+HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the database. A database breach alone is
+insufficient to verify candidate keys -- the attacker must also compromise the secret. This provides a stronger security boundary
+than bcrypt, which stores everything needed for verification in the database itself.
### Performance comparison
@@ -75,11 +70,11 @@ This yields a roughly **1,000x cost reduction** in compute for verification work
### Attack model
-**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault).
-Without the secret, they cannot verify any candidate key against the stored hashes.
+**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault). Without the secret, they cannot
+verify any candidate key against the stored hashes.
-**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes
-exhaustive search computationally infeasible with current or foreseeable technology.
+**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes exhaustive search
+computationally infeasible with current or foreseeable technology.
## Why Ed25519 for token signing
@@ -92,31 +87,29 @@ Talos uses Ed25519 (EdDSA over Curve25519) as the default signing algorithm for
| Signature size | 64 bytes | 256 bytes |
| Security level | 128 bits | 112 bits |
-Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of
-implementation vulnerabilities (unlike ECDSA P-256, where a weak nonce leaks the private key). It is
-also constant-time by design, providing immunity to timing side-channel attacks.
+Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of implementation vulnerabilities
+(unlike ECDSA P-256, where a weak nonce leaks the private key). It is also constant-time by design, providing immunity to timing
+side-channel attacks.
-RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not
-support EdDSA. The signing algorithm is determined by the `alg` field in the JWK configuration.
+RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not support EdDSA. The signing
+algorithm is determined by the `alg` field in the JWK configuration.
## Security requirements
For the cryptographic model to hold, the following operational requirements must be met:
-1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g.,
- HashiCorp Vault, AWS Secrets Manager). It must never be stored in the database or committed to
- version control. Talos supports zero-downtime rotation by maintaining current and retired
- secrets.
+1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g., HashiCorp Vault, AWS Secrets
+ Manager). It must never be stored in the database or committed to version control. Talos supports zero-downtime rotation by
+ maintaining current and retired secrets.
-2. **Key entropy** -- API keys must be generated using a cryptographically secure random number
- generator with at least 128 bits of entropy. Talos generates keys internally; user-provided key
- material is not accepted for issued keys.
+2. **Key entropy** -- API keys must be generated using a cryptographically secure random number generator with at least 128 bits
+ of entropy. Talos generates keys internally; user-provided key material is not accepted for issued keys.
-3. **Transport security** -- All communication must use TLS. API key secrets must never appear in
- URLs, query parameters, or log output.
+3. **Transport security** -- All communication must use TLS. API key secrets must never appear in URLs, query parameters, or log
+ output.
-4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored
- securely and never exposed through API responses or logs.
+4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored securely and never exposed
+ through API responses or logs.
## Industry precedent
@@ -127,5 +120,5 @@ Major cloud providers use HMAC for API key authentication:
- **Stripe** -- HMAC for API authentication and webhook signature verification
- **GitHub** -- HMAC-SHA256 for webhook payload signatures
-These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and
-verification throughput is a critical operational requirement.
+These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and verification throughput is a
+critical operational requirement.
diff --git a/docs/talos/concepts/token-derivation-security.md b/docs/talos/concepts/token-derivation-security.md
index 3ab52bf2da..65cc45521e 100644
--- a/docs/talos/concepts/token-derivation-security.md
+++ b/docs/talos/concepts/token-derivation-security.md
@@ -7,26 +7,20 @@ description: Stateless verification model and revocation semantics for derived t
## Overview
-Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are
-**stateless capability tokens**: all security constraints are enforced at creation time, and
-verification requires no database access. This design gives predictable sub-millisecond
-verification, zero database load on the hot path, and straightforward edge deployment.
+Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are **stateless capability tokens**:
+all security constraints are enforced at creation time, and verification requires no database access. This design gives
+predictable sub-millisecond verification, zero database load on the hot path, and straightforward edge deployment.
## Creation-time enforcement
-When a token is derived via `POST /v2/tokens:derive`, all security constraints are enforced before
-the token is signed:
+When a token is derived via `POST /v2/tokens:derive`, all security constraints are enforced before the token is signed:
- **Parent key must be ACTIVE.** A revoked or expired parent key cannot produce new tokens.
-- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than
- the parent, never more.
-- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the
- parent key's expiration.
-- **Subject and owner are inherited.** These fields are copied from the parent and cannot be
- overridden.
+- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than the parent, never more.
+- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the parent key's expiration.
+- **Subject and owner are inherited.** These fields are copied from the parent and cannot be overridden.
-If any constraint is violated, the derivation request fails with an appropriate error code. No token
-is issued.
+If any constraint is violated, the derivation request fails with an appropriate error code. No token is issued.
## Verification-time behavior
@@ -35,13 +29,11 @@ Verifying a derived token is purely cryptographic. The system checks:
1. **Signature validity** -- the token was signed by a trusted JWK signing key.
2. **Expiration** -- the `exp` claim has not passed.
-There are no database lookups, no parent key status checks, and no scope re-validation against the
-parent. This produces:
+There are no database lookups, no parent key status checks, and no scope re-validation against the parent. This produces:
- **Low latency.** Verification completes in 1-2 ms compared to 5-10 ms with database round-trips.
- **Zero database load.** Derived token verification never touches the database.
-- **Edge deployability.** Verification nodes need only the public JWK set, not a database
- connection.
+- **Edge deployability.** Verification nodes need only the public JWK set, not a database connection.
- **High availability.** Verification is unaffected by database outages.
## Revocation model
@@ -49,30 +41,25 @@ parent. This produces:
When a parent API key is revoked:
- **New derivations are blocked.** Any attempt to derive from the revoked parent returns an error.
-- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and
- the token has not expired.
-- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a
- revocation error.
+- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and the token has not expired.
+- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a revocation error.
This behavior is intentional. It provides:
-- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full
- TTL.
-- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions
- simultaneously.
+- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full TTL.
+- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions simultaneously.
- **Graceful degradation.** Downstream systems have time to transition before tokens expire.
## Immediate revocation strategies
-If your threat model requires faster invalidation of derived tokens, use one or more of these
-approaches:
+If your threat model requires faster invalidation of derived tokens, use one or more of these approaches:
-- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently
- with minimal overhead. This is the primary recommended approach.
-- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos.
- Check the deny list during your application's authorization step.
-- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature
- verification immediately. This invalidates all derived tokens, not just those from one parent.
+- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently with minimal overhead. This is
+ the primary recommended approach.
+- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos. Check the deny list during your
+ application's authorization step.
+- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature verification immediately. This
+ invalidates all derived tokens, not just those from one parent.
## TTL guidelines
@@ -83,18 +70,15 @@ approaches:
| Sensitive operations | 1-5 min | Limits damage from token theft |
| Long-running batch jobs | Use parent key directly | Avoids re-derivation during long processes |
-Short TTLs are the simplest and most effective control. When combined with the stateless
-verification model, they give security properties equivalent to stateful parent-status checks
-without the latency or availability cost.
+Short TTLs are the simplest and most effective control. When combined with the stateless verification model, they give security
+properties equivalent to stateful parent-status checks without the latency or availability cost.
## Security properties
Derived tokens are capability tokens with time-bounded authority:
-1. **All constraints enforced at creation.** The token can only be issued if the parent passes all
- checks.
-2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered
- with.
+1. **All constraints enforced at creation.** The token can only be issued if the parent passes all checks.
+2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered with.
3. **Time-bounded exposure.** Short TTLs limit the window in which a compromised token is useful.
4. **Immutable claims.** Subject, owner, scopes, and expiry are sealed in the token.
5. **No privilege escalation.** Scopes can never exceed the parent's scopes at creation time.
diff --git a/docs/talos/concepts/token-format.md b/docs/talos/concepts/token-format.md
index 9651a6f663..00519c7dd8 100644
--- a/docs/talos/concepts/token-format.md
+++ b/docs/talos/concepts/token-format.md
@@ -21,10 +21,9 @@ Issued API keys follow a structured v1 format:
## How it works
-The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used
-for database lookup. The checksum is HMAC-SHA256 over the payload, enabling tamper detection.
+The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used for database lookup. The
+checksum is HMAC-SHA256 over the payload, enabling tamper detection.
-During verification, all configured secrets (current + retired) are tried, supporting zero-downtime
-secret rotation.
+During verification, all configured secrets (current + retired) are tried, supporting zero-downtime secret rotation.
See [Token format reference](../reference/token-format.md) for the full specification.
diff --git a/docs/talos/index.md b/docs/talos/index.md
index 8e8d94f9ba..5eea36a67f 100644
--- a/docs/talos/index.md
+++ b/docs/talos/index.md
@@ -4,12 +4,11 @@ title: Ory Talos
# Ory Talos
-Ory Talos is a high-performance API key management service. It handles the full lifecycle of API
-credentials: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
-macaroon), and revoking access.
+Ory Talos is a high-performance API key management service. It handles the full lifecycle of API credentials: issuing keys,
+verifying them at low latency, deriving short-lived tokens (JWT and macaroon), and revoking access.
-Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations**
-(verify, self-revoke) so you can scale and secure each path independently.
+Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations** (verify, self-revoke) so you
+can scale and secure each path independently.
## Choose your path
@@ -18,8 +17,7 @@ Talos separates **admin operations** (issue, rotate, revoke, derive) from **data
You're a developer building an application that needs API key authentication. Start here:
- **[Quickstart](./quickstart/index.md)** — issue and verify your first API key in 5 minutes
-- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying,
- importing keys, and deriving tokens
+- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying, importing keys, and deriving tokens
- **[Error handling](./integrate/error-handling.md)** — error codes and retry strategies
### I want to run Talos in production
@@ -27,27 +25,21 @@ You're a developer building an application that needs API key authentication. St
You're a platform engineer responsible for deploying and operating Talos. Start here:
- **[Install](./operate/install.md)** — binary install or build from source
-- **[Configure](./operate/configure.md)** — configuration file, environment variables, and
- hot-reload behavior
-- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane
- topologies
-- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and
- health endpoints
+- **[Configure](./operate/configure.md)** — configuration file, environment variables, and hot-reload behavior
+- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane topologies
+- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and health endpoints
## Editions
-**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key
-lifecycle, token derivation, and CLI.
+**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key lifecycle, token derivation,
+and CLI.
-**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed
-caching (Redis, in-memory), edge proxy nodes, and the admin UI. Pages that cover commercial-only
-features are marked with a "Commercial" badge.
+**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed caching (Redis, in-memory), edge
+proxy nodes, and the admin UI. Pages that cover commercial-only features are marked with a "Commercial" badge.
## Learn more
-- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching
- behavior
-- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint
- documentation
+- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching behavior
+- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint documentation
- **[CLI reference](./reference/index.md)** — command-line tool documentation
- **[Configuration reference](./reference/config.md)** — all configuration keys and their defaults
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.md
index 77012e937d..cf65e27a12 100644
--- a/docs/talos/integrate/batch-operations.md
+++ b/docs/talos/integrate/batch-operations.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Batch operations
-Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in
-parallel and return per-item results.
+Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in parallel and return per-item
+results.
@@ -94,11 +94,9 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
### Response format
The response contains a `results` array. Each element has the same fields as a single
-[verify response](./issue-and-verify.md#verification-response). Results are returned in the same
-order as the requests.
+[verify response](./issue-and-verify.md#verification-response). Results are returned in the same order as the requests.
-Invalid credentials return `active: false` with an `error_code` — they do not cause the batch
-request to fail.
+Invalid credentials return `active: false` with an `error_code` — they do not cause the batch request to fail.
### Limits
@@ -146,14 +144,13 @@ curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
### Response format
-The response includes a `results` array with per-item outcomes, plus `success_count` and
-`failure_count` counters. The HTTP response is `200 OK` if at least one key succeeds. Check
-`failure_count` and individual `error_code` fields to detect partial failures.
+The response includes a `results` array with per-item outcomes, plus `success_count` and `failure_count` counters. The HTTP
+response is `200 OK` if at least one key succeeds. Check `failure_count` and individual `error_code` fields to detect partial
+failures.
For the complete field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx).
-For batch import error codes, see the
-[error codes reference](../reference/error-codes.md#batch-import-error-codes).
+[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx). For batch import error
+codes, see the [error codes reference](../reference/error-codes.md#batch-import-error-codes).
### Limits
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.md
index 733eb3d91b..8f8ba8d7a2 100644
--- a/docs/talos/integrate/derive-tokens.md
+++ b/docs/talos/integrate/derive-tokens.md
@@ -7,15 +7,13 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Derive tokens
-Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived
-tokens when you need:
+Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived tokens when you need:
- **Browser-safe credentials** — JWTs can be verified client-side without hitting the server.
- **Temporary access** — grant time-limited access with a subset of the parent key's scopes.
- **Custom claims** — embed application-specific data in the token.
-Derived tokens inherit permissions from the parent API key and can be verified on the same data
-plane endpoint.
+Derived tokens inherit permissions from the parent API key and can be verified on the same data plane endpoint.
@@ -105,15 +103,14 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or
-`TOKEN_ALGORITHM_MACAROON`), optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For
-the complete field reference, see the
+The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or `TOKEN_ALGORITHM_MACAROON`),
+optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
### Response
-The response contains a `token` object with `token.token` (the derived token string),
-`token.expire_time`, `token.scopes`, and `token.claims`. For the complete field reference, see the
+The response contains a `token` object with `token.token` (the derived token string), `token.expire_time`, `token.scopes`, and
+`token.claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
## Verify a derived token
@@ -207,14 +204,14 @@ curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
-Configure your JWT library to fetch keys from this URL. The keys are loaded from the server's JWKS
-configuration and are typically cached.
+Configure your JWT library to fetch keys from this URL. The keys are loaded from the server's JWKS configuration and are typically
+cached.
## Scope restrictions
-Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any
-scope that the parent key does not have, the request fails with a `403 Forbidden` error. To restrict
-scopes, request only scopes that exist on the parent key.
+Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any scope that the parent key
+does not have, the request fails with a `403 Forbidden` error. To restrict scopes, request only scopes that exist on the parent
+key.
## Next steps
diff --git a/docs/talos/integrate/error-handling.md b/docs/talos/integrate/error-handling.md
index b2196626dc..1986a5925f 100644
--- a/docs/talos/integrate/error-handling.md
+++ b/docs/talos/integrate/error-handling.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Error handling
-All Talos API errors follow a consistent JSON format. This guide covers the error response
-structure, common error codes, and retry strategies.
+All Talos API errors follow a consistent JSON format. This guide covers the error response structure, common error codes, and
+retry strategies.
@@ -37,9 +37,8 @@ Error responses use this structure:
## Verification errors
-The verify endpoint (`POST /v2/admin/apiKeys:verify`) returns errors differently from admin
-endpoints. Instead of an HTTP error, it returns `200 OK` with `is_active: false` and a structured
-error code:
+The verify endpoint (`POST /v2/admin/apiKeys:verify`) returns errors differently from admin endpoints. Instead of an HTTP error,
+it returns `200 OK` with `is_active: false` and a structured error code:
```json
{
@@ -54,8 +53,7 @@ For the complete list of verification error codes (`VERIFICATION_ERROR_*`), see
## HTTP status codes
-For the complete list of HTTP status codes and error IDs, see the
-[error codes reference](../reference/error-codes.md).
+For the complete list of HTTP status codes and error IDs, see the [error codes reference](../reference/error-codes.md).
Key categories:
@@ -66,8 +64,7 @@ Key categories:
### Safe to retry
-- **503 Service Unavailable** — the server is temporarily overloaded. Retry with exponential
- backoff.
+- **503 Service Unavailable** — the server is temporarily overloaded. Retry with exponential backoff.
- **504 Gateway Timeout** — the request timed out. Retry with backoff.
- **Network errors** — connection refused, DNS failure, etc. Retry with backoff.
@@ -78,8 +75,8 @@ Key categories:
### Idempotency key
-When issuing API keys, you can include a `request_id` in the request body. This field is stored with
-the key for client-side deduplication:
+When issuing API keys, you can include a `request_id` in the request body. This field is stored with the key for client-side
+deduplication:
@@ -107,8 +104,8 @@ curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
-The `request_id` is recorded in the key's metadata. The server does not enforce server-side
-idempotent replay (sending the same `request_id` twice creates two keys).
+The `request_id` is recorded in the key's metadata. The server does not enforce server-side idempotent replay (sending the same
+`request_id` twice creates two keys).
## Recommended backoff
diff --git a/docs/talos/integrate/import-keys.md b/docs/talos/integrate/import-keys.md
index 2f9e6c2d9c..4b61fdf450 100644
--- a/docs/talos/integrate/import-keys.md
+++ b/docs/talos/integrate/import-keys.md
@@ -7,19 +7,17 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Import existing keys
-Talos can manage API keys that were created outside the system. Import lets you migrate from a
-legacy key management solution or centralize keys from multiple providers without rotating
-credentials. For large migrations, use the batchImport API to import up to 1000 keys in a single
-request.
+Talos can manage API keys that were created outside the system. Import lets you migrate from a legacy key management solution or
+centralize keys from multiple providers without rotating credentials. For large migrations, use the batchImport API to import up
+to 1000 keys in a single request.
## How import works
-When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original
-key is never stored. Verification works by computing the same hash and looking it up in the
-database.
+When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original key is never stored.
+Verification works by computing the same hash and looking it up in the database.
-Imported keys support the same features as issued keys: scopes, metadata, expiration, token
-derivation (JWT/macaroon), and revocation.
+Imported keys support the same features as issued keys: scopes, metadata, expiration, token derivation (JWT/macaroon), and
+revocation.
@@ -73,16 +71,14 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`,
-`ttl`, and `metadata`. For the complete field reference, see the
-[ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
+The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`, `ttl`, and `metadata`. For
+the complete field reference, see the [ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
The response returns an `imported_api_key` object. The `raw_key` is **never returned** after import.
## Verify an imported key
-Imported keys use the same verification endpoint as issued keys. The data plane automatically
-detects the credential type:
+Imported keys use the same verification endpoint as issued keys. The data plane automatically detects the credential type:
@@ -142,14 +138,12 @@ curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
### Batch response
-The response includes a `results` array with per-item outcomes (`imported_api_key` on success,
-`error_code` and `error_message` on failure), plus `success_count` and `failure_count` counters. If
-at least one key succeeds, the HTTP response is `200 OK`.
+The response includes a `results` array with per-item outcomes (`imported_api_key` on success, `error_code` and `error_message` on
+failure), plus `success_count` and `failure_count` counters. If at least one key succeeds, the HTTP response is `200 OK`.
For the complete response field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx).
-For batch import error codes, see the
-[error codes reference](../reference/error-codes.md#batch-import-error-codes).
+[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx). For batch import error
+codes, see the [error codes reference](../reference/error-codes.md#batch-import-error-codes).
## List imported keys
diff --git a/docs/talos/integrate/index.md b/docs/talos/integrate/index.md
index fb94a7e99e..4713b7ac01 100644
--- a/docs/talos/integrate/index.md
+++ b/docs/talos/integrate/index.md
@@ -7,13 +7,11 @@ description: Add API key authentication to your application
Ory Talos exposes two HTTP APIs that map to distinct responsibilities:
-- **Admin plane** (`/v2/admin/...`) — Create, update, rotate, and revoke API keys. Deploy behind
- your internal network or VPN.
-- **Data plane** (`/v2/apiKeys:...`) — Verify credentials at the edge. Designed for sub-millisecond
- latency with caching enabled.
+- **Admin plane** (`/v2/admin/...`) — Create, update, rotate, and revoke API keys. Deploy behind your internal network or VPN.
+- **Data plane** (`/v2/apiKeys:...`) — Verify credentials at the edge. Designed for sub-millisecond latency with caching enabled.
-Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the
-data plane every time a request arrives.
+Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the data plane every time a request
+arrives.
## Common workflows
@@ -30,14 +28,14 @@ data plane every time a request arrives.
## Authentication
-The admin plane does not enforce authentication by default. Protect it at the infrastructure level
-(VPN, service mesh, reverse proxy with mTLS). The data plane is public-facing and requires no
-authentication — callers supply the credential they want to verify.
+The admin plane does not enforce authentication by default. Protect it at the infrastructure level (VPN, service mesh, reverse
+proxy with mTLS). The data plane is public-facing and requires no authentication — callers supply the credential they want to
+verify.
## Request format
-All endpoints accept and return JSON with `Content-Type: application/json`. Field names use
-`snake_case` (for example `actor_id`, `key_id`, `expire_time`).
+All endpoints accept and return JSON with `Content-Type: application/json`. Field names use `snake_case` (for example `actor_id`,
+`key_id`, `expire_time`).
Durations accept both Go format (`168h`, `30m`, `1h30m`) and protobuf format (`604800s`).
diff --git a/docs/talos/integrate/ip-restrictions.md b/docs/talos/integrate/ip-restrictions.md
index d8c4c70e98..cb215b1eb0 100644
--- a/docs/talos/integrate/ip-restrictions.md
+++ b/docs/talos/integrate/ip-restrictions.md
@@ -7,9 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# IP restrictions
-IP restrictions let you limit which client IPs can use an API key. When enabled, verification
-rejects requests from IPs outside the allowed CIDR ranges. Keys without IP restrictions are
-unrestricted.
+IP restrictions let you limit which client IPs can use an API key. When enabled, verification rejects requests from IPs outside
+the allowed CIDR ranges. Keys without IP restrictions are unrestricted.
## Prerequisites
@@ -20,8 +19,8 @@ A running Talos server. See the [quickstart](../quickstart/index.md) to start on
## Configure client IP source
-By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server
-runs behind a reverse proxy or CDN, configure the correct header in your Talos config:
+By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server runs behind a reverse proxy
+or CDN, configure the correct header in your Talos config:
```yaml
serve:
@@ -37,13 +36,12 @@ Supported values:
- `CLIENT_IP_SOURCE_X_REAL_IP` — Nginx
- `CLIENT_IP_SOURCE_TRUE_CLIENT_IP` — Cloudflare Enterprise
-This is a global setting — all IP restriction checks use the same source. Set it once to match your
-infrastructure topology.
+This is a global setting — all IP restriction checks use the same source. Set it once to match your infrastructure topology.
## Issue a key with IP restrictions
-Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both
-individual IPs (with `/32` or `/128` suffix) and CIDR ranges:
+Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both individual IPs (with `/32` or `/128`
+suffix) and CIDR ranges:
@@ -126,8 +124,8 @@ The response includes the key metadata with `is_active: true`.
## Verification from a disallowed IP
-When the client IP is outside all allowed CIDR ranges, verification returns
-`VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does not reveal which CIDRs are configured.
+When the client IP is outside all allowed CIDR ranges, verification returns `VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does
+not reveal which CIDRs are configured.
For the full list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
@@ -242,12 +240,12 @@ For the complete import field reference, see the
## Behavior notes
-- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key
- is unrestricted (all IPs allowed).
+- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key is unrestricted (all IPs
+ allowed).
- **Cache TTL**: IP restriction changes take effect after the cache TTL expires. See
[cache configuration](../operate/cache/index.md) for TTL settings.
- **Fail-closed**: If client IP resolution fails, the request is denied.
-- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and
- `/128` for single IPv6 addresses.
-- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens
- (JWTs/macaroons). Token verification checks the key's IP restrictions at derivation time.
+- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and `/128` for single IPv6
+ addresses.
+- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens (JWTs/macaroons). Token verification
+ checks the key's IP restrictions at derivation time.
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.md
index 81f96491f1..adb31f47d7 100644
--- a/docs/talos/integrate/issue-and-verify.md
+++ b/docs/talos/integrate/issue-and-verify.md
@@ -7,13 +7,11 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Issue and verify API keys
-This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are
-executable and tested in CI.
+This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are executable and tested in CI.
## Prerequisites
-A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start
-one locally.
+A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start one locally.
@@ -73,8 +71,8 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`,
-`ttl`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
+The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`, `ttl`, `metadata`, and
+`rate_limit_policy`. For the complete field reference, see the
[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
### Response fields
@@ -82,8 +80,8 @@ The key fields are `name` (human-readable label), `actor_id` (key actor), and op
The response contains two top-level fields:
- **`issued_api_key`** — The key metadata (ID, name, actor, scopes, status, timestamps).
-- **`secret`** — The full API key credential. This value is returned **only once** and cannot be
- retrieved later. Store it securely.
+- **`secret`** — The full API key credential. This value is returned **only once** and cannot be retrieved later. Store it
+ securely.
For the complete metadata field reference, see the
[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
@@ -115,25 +113,21 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
### Verification response
-The response includes `is_active` (boolean), `key_id`, `actor_id`, `scopes`, `metadata`, and
-`expire_time` when valid. When `is_active` is `false`, `error_code` and `error_message` indicate the
-reason. When rate limit enforcement is enabled (Commercial), the response also includes
-`rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the
-complete field reference, see the
-[VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+The response includes `is_active` (boolean), `key_id`, `actor_id`, `scopes`, `metadata`, and `expire_time` when valid. When
+`is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled (Commercial),
+the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the complete
+field reference, see the [VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
### Verification error codes
-When `is_active` is `false`, the `error_code` field indicates why. Common codes include
-`VERIFICATION_ERROR_EXPIRED`, `VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and
-`VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's rate limit quota is exhausted). For
-the complete list, see the
+When `is_active` is `false`, the `error_code` field indicates why. Common codes include `VERIFICATION_ERROR_EXPIRED`,
+`VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and `VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's
+rate limit quota is exhausted). For the complete list, see the
[verification error codes reference](../reference/error-codes.md#verification-error-codes).
## Cache bypass
-Verification results are cached for performance. After revoking a key, you can bypass the cache for
-immediate consistency:
+Verification results are cached for performance. After revoking a key, you can bypass the cache for immediate consistency:
```bash
curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
@@ -200,9 +194,8 @@ curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
### Query parameters
-Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status`
-(filtering). For the complete parameter reference, see the
-[ListIssuedAPIKeys API reference](../reference/api/admin-plane-service-list-issued-api-keys.api.mdx).
+Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status` (filtering). For the complete
+parameter reference, see the [ListIssuedAPIKeys API reference](../reference/api/admin-plane-service-list-issued-api-keys.api.mdx).
The response includes a `next_page_token` field. When empty, you have reached the last page.
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.md
index 0d93dba544..8239f6a79f 100644
--- a/docs/talos/integrate/key-lifecycle.md
+++ b/docs/talos/integrate/key-lifecycle.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Key lifecycle
-After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All
-lifecycle operations use the admin plane.
+After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All lifecycle operations use the admin
+plane.
@@ -57,8 +57,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
## Update key metadata
-Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the
-secret:
+Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the secret:
@@ -92,11 +91,10 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
### Update mask
-The `update_mask` field controls which fields are modified. Only fields listed in `paths` are
-changed. This follows the [AIP-134](https://google.aip.dev/134) standard for partial updates.
+The `update_mask` field controls which fields are modified. Only fields listed in `paths` are changed. This follows the
+[AIP-134](https://google.aip.dev/134) standard for partial updates.
-Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete
-field reference, see the
+Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
## Rotate a key
@@ -146,8 +144,8 @@ echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Rotation response
-The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once),
-and `old_issued_api_key` (status `KEY_STATUS_REVOKED`). For the complete field reference, see the
+The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once), and `old_issued_api_key`
+(status `KEY_STATUS_REVOKED`). For the complete field reference, see the
[RotateIssuedAPIKey API reference](../reference/api/admin-plane-service-rotate-issued-api-key.api.mdx).
### Zero-downtime rotation
@@ -161,8 +159,7 @@ The `:rotate` endpoint revokes the old key immediately. For zero-downtime rotati
## Revoke a key
-Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache
-TTL):
+Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache TTL):
@@ -190,18 +187,16 @@ echo "Key revoked"
### Revocation reasons
Standard reasons include `REVOCATION_REASON_KEY_COMPROMISE`, `REVOCATION_REASON_SUPERSEDED`,
-`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only).
-For the complete list, see the
+`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only). For the complete list, see the
[RevokeAPIKey API reference](../reference/api/admin-plane-service-revoke-api-key.api.mdx).
-When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable
-explanation.
+When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable explanation.
### Revocation and caching
-Revocation takes effect in the database immediately. However, if caching is enabled, previously
-cached verification results may remain valid until the cache entry expires. To force immediate
-effect, use the `Cache-Control: no-cache` header on verification requests.
+Revocation takes effect in the database immediately. However, if caching is enabled, previously cached verification results may
+remain valid until the cache entry expires. To force immediate effect, use the `Cache-Control: no-cache` header on verification
+requests.
## Verify after revocation
diff --git a/docs/talos/integrate/rate-limiting.md b/docs/talos/integrate/rate-limiting.md
index ed34a38473..20aef9f956 100644
--- a/docs/talos/integrate/rate-limiting.md
+++ b/docs/talos/integrate/rate-limiting.md
@@ -7,23 +7,21 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Rate limiting
-Rate limit policies let you cap how many verification requests a key can serve within a time window.
-Talos stores the policy on the key, returns it in verification responses, and -- in the Commercial
-edition -- enforces it server-side. For background on how enforcement works in each edition, see the
-[rate limiting concepts page](../concepts/rate-limiting.md).
+Rate limit policies let you cap how many verification requests a key can serve within a time window. Talos stores the policy on
+the key, returns it in verification responses, and -- in the Commercial edition -- enforces it server-side. For background on how
+enforcement works in each edition, see the [rate limiting concepts page](../concepts/rate-limiting.md).
## Prerequisites
-A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to
-start one locally.
+A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to start one locally.
## Attach a rate limit policy
-Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a
-`window` (time window as a duration string, e.g. `"60s"`):
+Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a `window` (time window as a
+duration string, e.g. `"60s"`):
@@ -72,14 +70,12 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
-The response includes the full key metadata with the `rate_limit_policy` attached. For the complete
-request and response field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+The response includes the full key metadata with the `rate_limit_policy` attached. For the complete request and response field
+reference, see the [IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
## Verify a rate-limited key
-Verify the key as you would any other credential. When the key has a rate limit policy, the response
-includes the policy metadata:
+Verify the key as you would any other credential. When the key has a rate limit policy, the response includes the policy metadata:
@@ -100,16 +96,14 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
-When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining`
-(approximate requests available before the limit is reached) and `rate_limit_reset_time` (when full
-capacity is recovered). For the complete response field reference, see the
-[VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining` (approximate requests available
+before the limit is reached) and `rate_limit_reset_time` (when full capacity is recovered). For the complete response field
+reference, see the [VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
## Exceeding the limit
-When a key's quota is exhausted, verification returns `is_active: false` with error code
-`VERIFICATION_ERROR_RATE_LIMITED` (Commercial edition). The response body includes the error code
-and a human-readable message:
+When a key's quota is exhausted, verification returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`
+(Commercial edition). The response body includes the error code and a human-readable message:
```json
{
@@ -119,17 +113,15 @@ and a human-readable message:
}
```
-The HTTP response also includes a `Retry-After` header indicating how many seconds the client should
-wait before retrying. In the OSS edition, enforcement is external -- Talos always returns the policy
-metadata but does not reject requests based on quota.
+The HTTP response also includes a `Retry-After` header indicating how many seconds the client should wait before retrying. In the
+OSS edition, enforcement is external -- Talos always returns the policy metadata but does not reject requests based on quota.
For the complete list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
## Update rate limit policy
-Use `PATCH` to change a key's rate limit policy without rotating the secret. Include
-`rate_limit_policy` in the `update_mask`:
+Use `PATCH` to change a key's rate limit policy without rotating the secret. Include `rate_limit_policy` in the `update_mask`:
@@ -159,9 +151,8 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
-The updated policy takes effect on the next verification request (subject to cache TTL). For the
-complete update field reference, see the
-[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+The updated policy takes effect on the next verification request (subject to cache TTL). For the complete update field reference,
+see the [UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
## Remove rate limit policy
@@ -196,8 +187,7 @@ Once removed, the key is no longer subject to rate limiting.
## HTTP response headers
-When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in
-verification responses:
+When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in verification responses:
| Header | When present | Description |
| ------------------ | -------------------- | -------------------------------------------------- |
@@ -205,25 +195,22 @@ verification responses:
| `RateLimit` | Always (with policy) | Current state: `limit=100, remaining=42, reset=18` |
| `Retry-After` | Only when limited | Seconds to wait before the next allowed request |
-These headers are present in both editions. In the OSS edition, your API gateway can read them to
-apply enforcement. In the Commercial edition, clients can use them for backoff and retry logic.
+These headers are present in both editions. In the OSS edition, your API gateway can read them to apply enforcement. In the
+Commercial edition, clients can use them for backoff and retry logic.
## Behavior notes
-- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is
- down), verification succeeds but rate limit metadata is omitted. Limiter failures never block
- legitimate traffic.
-- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result
- is served from cache, the rate limiter is not consulted. This means cached responses do not
- decrement the counter.
-- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets,
- even if they belong to the same actor.
-- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate
- effect, use the `Cache-Control: no-cache` header on verification requests.
+- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is down), verification succeeds but
+ rate limit metadata is omitted. Limiter failures never block legitimate traffic.
+- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result is served from cache, the
+ rate limiter is not consulted. This means cached responses do not decrement the counter.
+- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets, even if they belong to the
+ same actor.
+- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate effect, use the
+ `Cache-Control: no-cache` header on verification requests.
## Next steps
-- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs.
- Commercial
+- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs. Commercial
- [Key lifecycle](./key-lifecycle.md) -- update, rotate, and revoke keys
- [Error handling](./error-handling.md) -- error response format and retry logic
diff --git a/docs/talos/integrate/sdk/go.md b/docs/talos/integrate/sdk/go.md
index cfa25ae689..b98ca84dbf 100644
--- a/docs/talos/integrate/sdk/go.md
+++ b/docs/talos/integrate/sdk/go.md
@@ -5,13 +5,12 @@ description: Using the generated Go HTTP client
# Go SDK
-Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is
-generated using `openapi-generator` and lives in the `internal/client/generated` package.
+Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is generated using `openapi-generator`
+and lives in the `internal/client/generated` package.
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by
-external Go modules. It is used for Talos's own integration tests and the admin UI backend. If you
-need a Go client for your application, generate one from the OpenAPI spec at
-`api/talos.openapi-v2.json` using [OpenAPI Generator](https://openapi-generator.tech/). :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. It is used for
+Talos's own integration tests and the admin UI backend. If you need a Go client for your application, generate one from the
+OpenAPI spec at `api/talos.openapi-v2.json` using [OpenAPI Generator](https://openapi-generator.tech/). :::
@@ -25,12 +24,11 @@ openapi-generator generate \
-o generated/go-client
```
-The examples below use the internal client's types for illustration. A generated external client has
-the same API shape.
+The examples below use the internal client's types for illustration. A generated external client has the same API shape.
:::tip Full working example See
-[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go)
-for a complete, runnable program that exercises all operations shown below. :::
+[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go) for a
+complete, runnable program that exercises all operations shown below. :::
@@ -188,5 +186,4 @@ The Go SDK is regenerated with:
make generate-sdk
```
-This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to
-`internal/client/generated/`.
+This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to `internal/client/generated/`.
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.md
index da97d91524..050618b116 100644
--- a/docs/talos/integrate/self-revocation.md
+++ b/docs/talos/integrate/self-revocation.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Self-revocation
-The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the
-secret. This is a data plane operation — it does not require admin access.
+The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the secret. This is a data plane
+operation — it does not require admin access.
## Prerequisites
@@ -124,17 +124,14 @@ fi
-The request requires `credential` (the full API key secret) and optionally `reason` (revocation
-reason enum). For the complete field reference, see the
-[SelfRevokeAPIKey API reference](../reference/api/data-plane-service-self-revoke-api-key.api.mdx).
+The request requires `credential` (the full API key secret) and optionally `reason` (revocation reason enum). For the complete
+field reference, see the [SelfRevokeAPIKey API reference](../reference/api/data-plane-service-self-revoke-api-key.api.mdx).
-Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are
-stateless and cannot be revoked. All revocation reasons except
-`REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
+Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are stateless and cannot be revoked.
+All revocation reasons except `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
revocations.
-A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is
-immediately revoked.
+A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is immediately revoked.
## Admin vs self-revocation
diff --git a/docs/talos/operate/benchmarks.md b/docs/talos/operate/benchmarks.md
index 68470f42e7..ed8ee014ce 100644
--- a/docs/talos/operate/benchmarks.md
+++ b/docs/talos/operate/benchmarks.md
@@ -5,21 +5,20 @@ description: Performance benchmarks and load testing for Ory Talos
# Benchmarks
-Talos includes a k6-based load test suite that measures throughput, latency, and correctness under
-concurrent load. Use these benchmarks to validate your deployment and catch performance regressions.
+Talos includes a k6-based load test suite that measures throughput, latency, and correctness under concurrent load. Use these
+benchmarks to validate your deployment and catch performance regressions.
:::note
-These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS
-edition uses SQLite, which does not support concurrent writers and cannot handle the parallel load
-generated by multi-VU test profiles.
+These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS edition uses SQLite, which
+does not support concurrent writers and cannot handle the parallel load generated by multi-VU test profiles.
:::
## Reference results
-Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress
-profile (ramping 0→437 VUs over 5 minutes):
+Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress profile (ramping 0→437 VUs
+over 5 minutes):
| Metric | Value |
| ------------------- | ------------ |
@@ -52,8 +51,8 @@ The stress profile ramps through four stages:
4. **Hold**: 150 VUs for 120s
5. **Ramp down**: 150→0 VUs over 30s
-Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write
-scenarios (create, rotate, revoke, import, update, self-revoke) get ~30%.
+Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write scenarios (create, rotate,
+revoke, import, update, self-revoke) get ~30%.
## Running benchmarks
@@ -76,8 +75,8 @@ TEST_PROFILE=load bash test/load/run.sh
TEST_PROFILE=stress bash test/load/run.sh
```
-The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker,
-runs migrations, seeds tenant data, starts the server, and executes k6.
+The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker, runs migrations, seeds tenant
+data, starts the server, and executes k6.
### Using an existing database
@@ -125,12 +124,10 @@ Each profile enforces regression thresholds. Tests fail if any threshold is brea
After a k6 run, look for:
- **`checks` rate**: Must be 100%. Any failure indicates a correctness bug.
-- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases
- suggest a regression.
+- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases suggest a regression.
- **`http_req_failed` rate**: Should be 0% for smoke/load. Under 1% for stress.
-- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against
- the reference results to detect throughput regressions.
+- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against the reference results to
+ detect throughput regressions.
- **`iteration_duration`**: End-to-end time for each VU iteration including all operations.
-Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json`
-(machine-readable).
+Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json` (machine-readable).
diff --git a/docs/talos/operate/cache/index.md b/docs/talos/operate/cache/index.md
index e5037c98be..10760e2546 100644
--- a/docs/talos/operate/cache/index.md
+++ b/docs/talos/operate/cache/index.md
@@ -24,8 +24,8 @@ cache:
## Consistency
-Caching introduces eventual consistency. A revoked key may continue to pass verification until the
-cache entry expires (default: 5 minutes).
+Caching introduces eventual consistency. A revoked key may continue to pass verification until the cache entry expires (default: 5
+minutes).
-**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for
-individual requests when immediate consistency is required.
+**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for individual requests when
+immediate consistency is required.
diff --git a/docs/talos/operate/cache/memory.md b/docs/talos/operate/cache/memory.md
index 2f08db13e9..1fba0276b4 100644
--- a/docs/talos/operate/cache/memory.md
+++ b/docs/talos/operate/cache/memory.md
@@ -7,8 +7,7 @@ sidebar_custom_props:
# In-memory cache
-The in-memory cache stores verification results in the Talos process using a ristretto-based LRU
-cache.
+The in-memory cache stores verification results in the Talos process using a ristretto-based LRU cache.
## Configuration
@@ -30,6 +29,5 @@ cache:
## When to use
-Use the in-memory cache for single-node deployments or when each Talos instance handles enough
-traffic to benefit from local caching. For multi-instance deployments, consider [Redis](redis.md)
-for shared cache across all instances.
+Use the in-memory cache for single-node deployments or when each Talos instance handles enough traffic to benefit from local
+caching. For multi-instance deployments, consider [Redis](redis.md) for shared cache across all instances.
diff --git a/docs/talos/operate/cache/redis.md b/docs/talos/operate/cache/redis.md
index 9e9064d7b2..cc24e1fa63 100644
--- a/docs/talos/operate/cache/redis.md
+++ b/docs/talos/operate/cache/redis.md
@@ -35,6 +35,5 @@ cache:
## When to use
-Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances,
-reducing database load. Redis is also required for [edge proxy](../deploy/edge-proxy.md) deployments
-where each edge node shares a regional Redis instance.
+Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances, reducing database load. Redis
+is also required for [edge proxy](../deploy/edge-proxy.md) deployments where each edge node shares a regional Redis instance.
diff --git a/docs/talos/operate/configure.md b/docs/talos/operate/configure.md
index 4bad1b1897..25fe5d5d51 100644
--- a/docs/talos/operate/configure.md
+++ b/docs/talos/operate/configure.md
@@ -5,15 +5,13 @@ description: Configuration reference for Ory Talos
# Configure
-Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set
-through environment variables or CLI flags. See the
-[Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
+Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set through environment variables
+or CLI flags. See the [Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
environment variable mappings, and precedence rules.
## Hot-reload
-Talos watches the config file for changes. Some settings reload automatically, others require a
-restart.
+Talos watches the config file for changes. Some settings reload automatically, others require a restart.
**Hot-reloadable:**
@@ -108,5 +106,5 @@ tracing:
sample_rate: 0.01
```
-See the [Configuration reference](../reference/config.md) for all available keys with types,
-defaults, and environment variable mappings.
+See the [Configuration reference](../reference/config.md) for all available keys with types, defaults, and environment variable
+mappings.
diff --git a/docs/talos/operate/database/cockroachdb.md b/docs/talos/operate/database/cockroachdb.md
index cf38a55d61..9e8160f63e 100644
--- a/docs/talos/operate/database/cockroachdb.md
+++ b/docs/talos/operate/database/cockroachdb.md
@@ -32,23 +32,20 @@ export TALOS_DB_DSN="cockroach://talos@crdb:26257/talos?sslmode=verify-full&max_
cockroach://user:password@host:port/dbname?param=value¶m=value
```
-Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted
-to `postgres://` since CockroachDB uses the PostgreSQL wire protocol.
+Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted to `postgres://` since
+CockroachDB uses the PostgreSQL wire protocol.
## DSN parameters, connection pooling, and TLS
-CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including
-both standard and advanced pool modes. For the full parameter reference, see the
-[PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
-[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl)
-documentation.
+CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including both standard and advanced pool
+modes. For the full parameter reference, see the [PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
+[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl) documentation.
Key differences from PostgreSQL:
-- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of
- `25`.
-- **No connection limit pressure** — Each CockroachDB node independently manages connections, so
- total pool sizes can be larger without needing a connection pooler like PgBouncer.
+- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of `25`.
+- **No connection limit pressure** — Each CockroachDB node independently manages connections, so total pool sizes can be larger
+ without needing a connection pooler like PgBouncer.
## Migrations
@@ -58,9 +55,8 @@ talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
## Multi-region
-Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification
-latency. Talos does not require special configuration beyond pointing `db.dsn` at the local
-CockroachDB node.
+Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification latency. Talos does not require
+special configuration beyond pointing `db.dsn` at the local CockroachDB node.
```yaml
# Region: us-east-1
@@ -74,8 +70,7 @@ db:
## Performance
-CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For
-verification-heavy workloads:
+CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For verification-heavy workloads:
- Enable [caching](../cache/index.md) to absorb verification reads
- Use `max_conns=50` or higher — CockroachDB connections are lighter than PostgreSQL
diff --git a/docs/talos/operate/database/index.md b/docs/talos/operate/database/index.md
index 163f881cc3..9c520783f8 100644
--- a/docs/talos/operate/database/index.md
+++ b/docs/talos/operate/database/index.md
@@ -4,8 +4,7 @@ title: Database
# Database
-Talos stores API key data in a relational database. The backend is determined by the DSN scheme in
-`db.dsn`.
+Talos stores API key data in a relational database. The backend is determined by the DSN scheme in `db.dsn`.
## Supported backends
diff --git a/docs/talos/operate/database/mysql.md b/docs/talos/operate/database/mysql.md
index 9609924622..ff782cfdcc 100644
--- a/docs/talos/operate/database/mysql.md
+++ b/docs/talos/operate/database/mysql.md
@@ -32,18 +32,17 @@ export TALOS_DB_DSN="mysql://talos:secret@tcp(db:3306)/talos?tls=true&parseTime=
mysql://user:password@tcp(host:port)/dbname?param=value¶m=value
```
-The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before
-passing the DSN to the Go MySQL driver.
+The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before passing the DSN to the Go MySQL
+driver.
-:::caution Required parameter Always include `parseTime=true` in the DSN. Without it, datetime
-columns are returned as byte arrays instead of `time.Time`, causing runtime errors. :::
+:::caution Required parameter Always include `parseTime=true` in the DSN. Without it, datetime columns are returned as byte arrays
+instead of `time.Time`, causing runtime errors. :::
## DSN parameters
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
-database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
| Parameter | Type | Default | Description |
| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
@@ -90,8 +89,8 @@ Pool behavior:
### Pool sizing
-Start with 25 connections per instance. The total pool across all instances should stay below
-MySQL's `max_connections` (default: 151).
+Start with 25 connections per instance. The total pool across all instances should stay below MySQL's `max_connections` (default:
+151).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -99,9 +98,8 @@ MySQL's `max_connections` (default: 151).
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use ProxySQL or MySQL Router to multiplex |
-For large deployments, place [ProxySQL](https://proxysql.com/) or
-[MySQL Router](https://dev.mysql.com/doc/mysql-router/en/) between Talos and MySQL for connection
-multiplexing.
+For large deployments, place [ProxySQL](https://proxysql.com/) or [MySQL Router](https://dev.mysql.com/doc/mysql-router/en/)
+between Talos and MySQL for connection multiplexing.
## Database preparation
diff --git a/docs/talos/operate/database/postgresql.md b/docs/talos/operate/database/postgresql.md
index f482a5c953..98f230b91a 100644
--- a/docs/talos/operate/database/postgresql.md
+++ b/docs/talos/operate/database/postgresql.md
@@ -7,8 +7,8 @@ sidebar_custom_props:
# PostgreSQL
-PostgreSQL is the recommended production database backend. It provides connection pooling, ACID
-transactions, and high-availability via streaming replication.
+PostgreSQL is the recommended production database backend. It provides connection pooling, ACID transactions, and
+high-availability via streaming replication.
## Supported versions
@@ -39,8 +39,7 @@ Both `postgres://` and `postgresql://` schemes are accepted.
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
-database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
| Parameter | Type | Default | Description |
| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
@@ -71,8 +70,7 @@ Talos supports two pool modes for PostgreSQL, controlled by the `pool_mode` DSN
### Standard mode (default)
-Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with
-all tooling.
+Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with all tooling.
```yaml
db:
@@ -88,17 +86,16 @@ Pool behavior:
### Advanced mode
-Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is
-optimized for Kubernetes and cloud environments.
+Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is optimized for Kubernetes and cloud
+environments.
```yaml
db:
dsn: "postgres://talos:secret@db:5432/talos?pool_mode=advanced"
```
-In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the DSN.
-The `max_conns`, `max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters are not
-used — pgxpool manages its own pool.
+In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the DSN. The `max_conns`,
+`max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters are not used — pgxpool manages its own pool.
Use advanced mode when:
@@ -108,8 +105,8 @@ Use advanced mode when:
## Pool sizing
-Start with 25 connections per instance. The total pool across all instances must stay below
-PostgreSQL's `max_connections` (default: 100).
+Start with 25 connections per instance. The total pool across all instances must stay below PostgreSQL's `max_connections`
+(default: 100).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -117,9 +114,8 @@ PostgreSQL's `max_connections` (default: 100).
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use PgBouncer to multiplex connections |
-For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL.
-PgBouncer multiplexes many application connections over fewer database connections, allowing you to
-scale beyond PostgreSQL's connection limit.
+For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL. PgBouncer multiplexes many
+application connections over fewer database connections, allowing you to scale beyond PostgreSQL's connection limit.
## Migrations
diff --git a/docs/talos/operate/deploy/edge-proxy.md b/docs/talos/operate/deploy/edge-proxy.md
index 62a1dc690c..edb3e58238 100644
--- a/docs/talos/operate/deploy/edge-proxy.md
+++ b/docs/talos/operate/deploy/edge-proxy.md
@@ -7,8 +7,7 @@ sidebar_custom_props:
# Edge proxy
-Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification
-latency.
+Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification latency.
## Pattern
@@ -39,9 +38,9 @@ graph TB
## How it works
-The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos
-server. It intercepts `POST` requests to `/v2/verify/*` endpoints, caches positive (active)
-verification responses locally, and proxies everything else to upstream unchanged.
+The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos server. It intercepts `POST`
+requests to `/v2/verify/*` endpoints, caches positive (active) verification responses locally, and proxies everything else to
+upstream unchanged.
```mermaid
sequenceDiagram
@@ -64,13 +63,12 @@ sequenceDiagram
Proxy-->>App: 200 OK
```
-Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the
-proxy transparently.
+Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the proxy transparently.
## Sidecar deployment
-Run the proxy as a sidecar container alongside your application. Your application sends verify
-requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
+Run the proxy as a sidecar container alongside your application. Your application sends verify requests to `localhost` (sub-ms
+cache hits) instead of the central Talos server.
```
┌─────────────────────────────────┐
@@ -83,9 +81,8 @@ requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
└─────────────────────────────────┘
```
-Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy
-listens on). All other Talos API calls (admin, key management) should go directly to the central
-server.
+Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy listens on). All other Talos API
+calls (admin, key management) should go directly to the central server.
## Configuration
@@ -113,10 +110,9 @@ talos-commercial proxy \
### Cache key generation
-Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent
-collision attacks. The host component ensures tenant isolation in multi-tenant deployments: the same
-credential cached under `tenant-a.example.com` will not be served for requests from
-`tenant-b.example.com`.
+Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent collision attacks. The host
+component ensures tenant isolation in multi-tenant deployments: the same credential cached under `tenant-a.example.com` will not
+be served for requests from `tenant-b.example.com`.
### What gets cached
@@ -130,10 +126,9 @@ Inactive credentials, error responses, and non-verify endpoints are never cached
### TTL calculation
-The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the
-verification response includes an `expires_at` timestamp, the proxy ensures the cached entry expires
-no later than the credential itself. If `expires_at` is absent, the configured `--cache-ttl` is
-used.
+The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the verification response includes an
+`expires_at` timestamp, the proxy ensures the cached entry expires no later than the credential itself. If `expires_at` is absent,
+the configured `--cache-ttl` is used.
### Cache headers
@@ -155,8 +150,7 @@ curl -X POST http://localhost:8080/v2/verify/apiKey \
-d '{"credential": "phx_..."}'
```
-Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for
-caching.
+Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for caching.
## Health checks
@@ -268,10 +262,8 @@ spec:
## Eventual consistency
-Revocation takes effect in the database immediately but cached verification results persist until
-the cache TTL expires. To force an immediate re-check against upstream, send
-`Cache-Control: no-cache` on the verification request.
+Revocation takes effect in the database immediately but cached verification results persist until the cache TTL expires. To force
+an immediate re-check against upstream, send `Cache-Control: no-cache` on the verification request.
-Choose a `--cache-ttl` that balances latency savings against your revocation propagation
-requirements. Shorter TTLs provide faster revocation propagation at the cost of more upstream
-requests.
+Choose a `--cache-ttl` that balances latency savings against your revocation propagation requirements. Shorter TTLs provide faster
+revocation propagation at the cost of more upstream requests.
diff --git a/docs/talos/operate/deploy/separate-planes.md b/docs/talos/operate/deploy/separate-planes.md
index ed30a29b44..71f1b759ca 100644
--- a/docs/talos/operate/deploy/separate-planes.md
+++ b/docs/talos/operate/deploy/separate-planes.md
@@ -4,22 +4,18 @@ title: Separate admin and data planes
# Separate admin and data planes
-In production, you can deploy the admin plane and data plane as separate processes for independent
-scaling and security isolation.
+In production, you can deploy the admin plane and data plane as separate processes for independent scaling and security isolation.
## Why separate
-- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be
- exposed at the edge
-- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane
- handles lower-volume management
-- **Network isolation**: Admin plane behind internal firewall; data plane behind public load
- balancer
+- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be exposed at the edge
+- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane handles lower-volume
+ management
+- **Network isolation**: Admin plane behind internal firewall; data plane behind public load balancer
## Architecture
-Both planes share the same database. The admin plane writes keys; the data plane reads and verifies
-them.
+Both planes share the same database. The admin plane writes keys; the data plane reads and verifies them.
```mermaid
graph TB
@@ -53,8 +49,7 @@ talos serve check --config config.yaml
## Configuration
-Both deployments use the same config file or environment variables. The key difference is network
-exposure:
+Both deployments use the same config file or environment variables. The key difference is network exposure:
**Admin plane** — bind to internal network only:
@@ -79,5 +74,4 @@ cache:
## Network policies
-Restrict admin plane access to internal services only. Data plane can accept traffic from any
-source.
+Restrict admin plane access to internal services only. Data plane can accept traffic from any source.
diff --git a/docs/talos/operate/index.md b/docs/talos/operate/index.md
index 37e92dafb1..199e241dce 100644
--- a/docs/talos/operate/index.md
+++ b/docs/talos/operate/index.md
@@ -20,8 +20,7 @@ Before going to production, review these guides:
- **[Secrets management](secrets.md)** — configure HMAC secrets and JWKS signing keys
- **[TLS](tls.md)** — enable TLS termination or configure a reverse proxy
-- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and
- health checks
+- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and health checks
- **[Security hardening](security-hardening.md)** — production security checklist
- **[Benchmarks](benchmarks.md)** — performance baselines and load testing
@@ -29,8 +28,8 @@ Before going to production, review these guides:
These features require the Commercial edition:
-- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**,
- **[CockroachDB](database/cockroachdb.md)** — production-grade SQL backends
+- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**, **[CockroachDB](database/cockroachdb.md)** —
+ production-grade SQL backends
- **[Caching](cache/index.md)** — in-memory and Redis caching for sub-millisecond verification
- **[Edge proxy](deploy/edge-proxy.md)** — deploy data plane at the edge
- **[Multi-tenancy](multi-tenancy.md)** — serve multiple tenants from a single cluster
@@ -42,6 +41,5 @@ Talos separates administrative operations (issuing, revoking) from verification:
- **Admin plane** — manages key lifecycle. Runs behind your internal network.
- **Data plane** — verifies credentials at the edge. Horizontally scalable with caching.
-You can run both planes in a single process (`talos serve`) or split them for production
-(`talos serve admin`, `talos serve check`). See [Separate planes](deploy/separate-planes.md) for
-details.
+You can run both planes in a single process (`talos serve`) or split them for production (`talos serve admin`,
+`talos serve check`). See [Separate planes](deploy/separate-planes.md) for details.
diff --git a/docs/talos/operate/install.md b/docs/talos/operate/install.md
index 08e2d43961..5a6c271fed 100644
--- a/docs/talos/operate/install.md
+++ b/docs/talos/operate/install.md
@@ -23,8 +23,7 @@ The binary is at `.bin/talos`. SQLite is the only supported database backend in
### Commercial edition
-The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin
-UI:
+The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin UI:
```bash
go build -tags commercial -o .bin/talos-commercial .
diff --git a/docs/talos/operate/monitoring/health-checks.md b/docs/talos/operate/monitoring/health-checks.md
index eec21edfee..b3fce3f677 100644
--- a/docs/talos/operate/monitoring/health-checks.md
+++ b/docs/talos/operate/monitoring/health-checks.md
@@ -34,8 +34,8 @@ readinessProbe:
## Load balancer
-Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server
-is ready to accept traffic and 503 when it is not (e.g., during startup or shutdown).
+Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server is ready to accept traffic and
+503 when it is not (e.g., during startup or shutdown).
## Suppressing health logs
diff --git a/docs/talos/operate/monitoring/index.md b/docs/talos/operate/monitoring/index.md
index 003e735225..f0a92dbdad 100644
--- a/docs/talos/operate/monitoring/index.md
+++ b/docs/talos/operate/monitoring/index.md
@@ -4,8 +4,7 @@ title: Monitoring
# Monitoring
-Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health
-endpoints.
+Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health endpoints.
- [Prometheus metrics](metrics.md) — request counts, latencies, and pool sizes
- [OpenTelemetry tracing](tracing.md) — distributed request traces
diff --git a/docs/talos/operate/monitoring/tracing.md b/docs/talos/operate/monitoring/tracing.md
index 9bb00521b5..43baf48812 100644
--- a/docs/talos/operate/monitoring/tracing.md
+++ b/docs/talos/operate/monitoring/tracing.md
@@ -36,6 +36,5 @@ export TALOS_TRACING_SAMPLE_RATE=0.01
## Traced operations
-Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP
-request handling. Each trace includes the Network ID (for multi-tenant deployments) and relevant key
-identifiers.
+Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP request handling. Each trace
+includes the Network ID (for multi-tenant deployments) and relevant key identifiers.
diff --git a/docs/talos/operate/multi-tenancy.md b/docs/talos/operate/multi-tenancy.md
index 7094b4e298..fdb9cf9704 100644
--- a/docs/talos/operate/multi-tenancy.md
+++ b/docs/talos/operate/multi-tenancy.md
@@ -30,18 +30,16 @@ multitenancy:
config_path: "/etc/talos/tenant2.yaml"
```
-Each entry maps a hostname to a network. The `hostname` is matched against the incoming request's
-`Host` / `X-Forwarded-Host` header (port is stripped before comparison). The `id` is the tenant's
-UUID. The `config_path` points to a network-specific configuration file (absolute or relative to the
-working directory).
+Each entry maps a hostname to a network. The `hostname` is matched against the incoming request's `Host` / `X-Forwarded-Host`
+header (port is stripped before comparison). The `id` is the tenant's UUID. The `config_path` points to a network-specific
+configuration file (absolute or relative to the working directory).
## Database isolation
-Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every
-query includes the NID, ensuring complete data isolation at the SQL level.
+Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every query includes the NID, ensuring
+complete data isolation at the SQL level.
## Defense-in-depth
-Token claims embed the NID at derivation time. During verification, the claim NID is validated
-against the context NID (from hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`,
-preventing cross-tenant token replay.
+Token claims embed the NID at derivation time. During verification, the claim NID is validated against the context NID (from
+hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`, preventing cross-tenant token replay.
diff --git a/docs/talos/operate/secrets.md b/docs/talos/operate/secrets.md
index cd62b34281..882588739a 100644
--- a/docs/talos/operate/secrets.md
+++ b/docs/talos/operate/secrets.md
@@ -42,8 +42,8 @@ secrets:
- "old-secret-that-was-previously-current"
```
-During verification, Talos tries the current secret first, then each retired secret in order. This
-ensures existing API keys remain valid after rotation.
+During verification, Talos tries the current secret first, then each retired secret in order. This ensures existing API keys
+remain valid after rotation.
## Environment variables
diff --git a/docs/talos/operate/security-hardening.md b/docs/talos/operate/security-hardening.md
index 41b88027dc..930e6c9fef 100644
--- a/docs/talos/operate/security-hardening.md
+++ b/docs/talos/operate/security-hardening.md
@@ -6,19 +6,17 @@ title: Security hardening
## Network
-- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance
- and revocation and should never be exposed to the public internet.
-- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or
- terminate TLS at the load balancer).
+- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance and revocation and should never
+ be exposed to the public internet.
+- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or terminate TLS at the load
+ balancer).
- **Separate admin and data planes** in production for independent security boundaries.
## Secrets
-- **Use strong HMAC secrets** of at least 32 characters, generated with a cryptographically secure
- random generator.
+- **Use strong HMAC secrets** of at least 32 characters, generated with a cryptographically secure random generator.
- **Use separate HMAC secrets** (`secrets.hmac.current`) rather than relying on the default secret.
-- **Rotate secrets regularly** using the retired array. Verification tries current + retired secrets
- automatically.
+- **Rotate secrets regularly** using the retired array. Verification tries current + retired secrets automatically.
- **Never commit secrets** to version control. Use environment variables or a secrets manager.
## API keys
diff --git a/docs/talos/operate/tls.md b/docs/talos/operate/tls.md
index 6e630b71ba..5e108ed273 100644
--- a/docs/talos/operate/tls.md
+++ b/docs/talos/operate/tls.md
@@ -4,8 +4,7 @@ title: TLS configuration
# TLS configuration
-Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy,
-Caddy) for TLS termination:
+Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy, Caddy) for TLS termination:
```
Client --[HTTPS]--> Load Balancer --[HTTP]--> Talos
diff --git a/docs/talos/operate/troubleshooting.md b/docs/talos/operate/troubleshooting.md
index fecf8a0a5f..57082b79ca 100644
--- a/docs/talos/operate/troubleshooting.md
+++ b/docs/talos/operate/troubleshooting.md
@@ -29,8 +29,7 @@ Verify `serve.http.host` and `serve.http.port` in your config.
talos migrate status --database "sqlite:///path/to/db"
```
-If a migration failed partway through, inspect the database schema and retry with
-`talos migrate up`.
+If a migration failed partway through, inspect the database schema and retry with `talos migrate up`.
### Secret too short
@@ -45,13 +44,12 @@ Set `secrets.default.current` to a string of at least 32 characters.
1. Verify the key was issued on the same Talos instance (or shared database)
2. Check if the key has been revoked: `GET /v2/admin/issuedApiKeys/{key_id}`
3. If using caching, try with `Cache-Control: no-cache` header
-4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was
- issued
+4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was issued
### Invalid API key format
-The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret
-(not the key_id) is being sent.
+The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret (not the key_id) is being
+sent.
## Debug logging
diff --git a/docs/talos/quickstart/docker-commercial.md b/docs/talos/quickstart/docker-commercial.md
index 7ced0fb435..193d9345e0 100644
--- a/docs/talos/quickstart/docker-commercial.md
+++ b/docs/talos/quickstart/docker-commercial.md
@@ -109,8 +109,7 @@ docker compose -f docker-compose.commercial.yaml down -v
## Prerequisites
-You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free
-edition first.
+You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free edition first.
## Next steps
diff --git a/docs/talos/quickstart/index.md b/docs/talos/quickstart/index.md
index 0648e2026d..651c176a7c 100644
--- a/docs/talos/quickstart/index.md
+++ b/docs/talos/quickstart/index.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Quickstart
-This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker
-Compose. You need Docker. Examples use the Talos CLI (with curl as an alternative).
+This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker Compose. You need Docker.
+Examples use the Talos CLI (with curl as an alternative).
@@ -19,8 +19,8 @@ Compose. You need Docker. Examples use the Talos CLI (with curl as an alternativ
docker compose -f docker-compose.oss.yaml up --build -d
```
-This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at
-http://localhost:3001). Migrations run automatically.
+This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at http://localhost:3001). Migrations run
+automatically.
Wait for the server to become healthy:
@@ -128,8 +128,7 @@ echo "$VERIFY_RESPONSE" | jq .
-The response confirms the key is active and returns the associated metadata (actor, scopes,
-expiration).
+The response confirms the key is active and returns the associated metadata (actor, scopes, expiration).
## Revoke the key
@@ -193,8 +192,8 @@ fi
-Revocation is immediate. Even though the key is cryptographically valid, the server checks the
-revocation list on every verification request.
+Revocation is immediate. Even though the key is cryptographically valid, the server checks the revocation list on every
+verification request.
## Stop the server
@@ -210,7 +209,6 @@ docker compose -f docker-compose.oss.yaml down -v
## Next steps
-- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential
- operations
+- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential operations
- **[Operations guide](../operate/index.md)** — install, configure, and deploy Talos in production
- **[Architecture](../concepts/architecture.md)** — how the admin and data planes work
diff --git a/docs/talos/reference/api.json b/docs/talos/reference/api.json
new file mode 100644
index 0000000000..97e03892cb
--- /dev/null
+++ b/docs/talos/reference/api.json
@@ -0,0 +1,1631 @@
+{
+ "components": {
+ "schemas": {
+ "StaticCredentialsAdminRevokeAPIKeyBody": {
+ "properties": {
+ "description": {
+ "description": "Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.",
+ "type": "string"
+ },
+ "reason": {
+ "$ref": "#/components/schemas/v2RevocationReason"
+ }
+ },
+ "type": "object"
+ },
+ "StaticCredentialsAdminRotateIssuedAPIKeyBody": {
+ "properties": {
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "metadata": {
+ "title": "metadata for the new API key (inherits from old key if not provided)",
+ "type": "object"
+ },
+ "name": {
+ "title": "name for the new API key (inherits from old key if not provided)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "title": "scopes for the new API key (inherits from old key if not provided)",
+ "type": "array"
+ },
+ "update_mask": {
+ "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "type": "object"
+ },
+ "StaticCredentialsAdminUpdateImportedAPIKeyBody": {
+ "properties": {
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "update_mask": {
+ "title": "AIP-134 partial update mask",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "StaticCredentialsAdminUpdateIssuedAPIKeyBody": {
+ "properties": {
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "update_mask": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "protobufAny": {
+ "additionalProperties": {},
+ "properties": {
+ "@type": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "protobufNullValue": {
+ "default": "NULL_VALUE",
+ "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value.",
+ "enum": ["NULL_VALUE"],
+ "type": "string"
+ },
+ "rpcStatus": {
+ "properties": {
+ "code": {
+ "format": "int32",
+ "type": "integer"
+ },
+ "details": {
+ "items": {
+ "$ref": "#/components/schemas/protobufAny"
+ },
+ "type": "array"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2BatchImportAPIKeysRequest": {
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "properties": {
+ "requests": {
+ "items": {
+ "$ref": "#/components/schemas/v2ImportAPIKeyRequest"
+ },
+ "title": "Keys to import",
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "v2BatchImportAPIKeysResponse": {
+ "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
+ "properties": {
+ "failure_count": {
+ "format": "int32",
+ "type": "integer"
+ },
+ "results": {
+ "items": {
+ "$ref": "#/components/schemas/v2BatchImportResult"
+ },
+ "type": "array"
+ },
+ "success_count": {
+ "format": "int32",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "v2BatchImportErrorCode": {
+ "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
+ "enum": [
+ "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
+ "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
+ "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
+ "BATCH_IMPORT_ERROR_INTERNAL"
+ ],
+ "type": "string"
+ },
+ "v2BatchImportResult": {
+ "description": "BatchImportResult contains the result for one key in a batch import request.",
+ "properties": {
+ "error_code": {
+ "$ref": "#/components/schemas/v2BatchImportErrorCode"
+ },
+ "error_message": {
+ "title": "Human-readable failure reason",
+ "type": "string"
+ },
+ "imported_api_key": {
+ "$ref": "#/components/schemas/v2ImportedAPIKey"
+ },
+ "index": {
+ "format": "int32",
+ "title": "Zero-based index in request.requests",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "v2BatchVerifyAPIKeysRequest": {
+ "properties": {
+ "requests": {
+ "items": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "v2BatchVerifyAPIKeysResponse": {
+ "properties": {
+ "results": {
+ "items": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "v2DeriveTokenRequest": {
+ "properties": {
+ "algorithm": {
+ "$ref": "#/components/schemas/v2TokenAlgorithm"
+ },
+ "credential": {
+ "title": "The API key secret (issued or imported) to derive a token from",
+ "type": "string"
+ },
+ "custom_claims": {
+ "type": "object"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ }
+ },
+ "title": "Token derivation messages",
+ "type": "object"
+ },
+ "v2DeriveTokenResponse": {
+ "properties": {
+ "token": {
+ "$ref": "#/components/schemas/v2Token"
+ }
+ },
+ "type": "object"
+ },
+ "v2GetJWKSResponse": {
+ "properties": {
+ "jwks": {
+ "title": "JSON Web Key Set",
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "v2IPRestriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "v2ImportAPIKeyRequest": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "actor_id": {
+ "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ },
+ "v2ImportAPIKeyResponse": {
+ "properties": {
+ "imported_api_key": {
+ "$ref": "#/components/schemas/v2ImportedAPIKey"
+ }
+ },
+ "type": "object"
+ },
+ "v2ImportedAPIKey": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": {
+ "type": "string"
+ },
+ "create_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "$ref": "#/components/schemas/v2RevocationReason"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "$ref": "#/components/schemas/v2KeyStatus"
+ },
+ "update_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "type": "object"
+ },
+ "v2IssueAPIKeyRequest": {
+ "properties": {
+ "actor_id": {
+ "type": "string"
+ },
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "type": "object"
+ },
+ "v2IssueAPIKeyResponse": {
+ "properties": {
+ "issued_api_key": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "Only returned on creation",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2IssuedAPIKey": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": {
+ "type": "string"
+ },
+ "create_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "$ref": "#/components/schemas/v2IPRestriction"
+ },
+ "key_id": {
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "name": {
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "$ref": "#/components/schemas/v2RevocationReason"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "$ref": "#/components/schemas/v2KeyStatus"
+ },
+ "update_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "type": "object"
+ },
+ "v2KeyStatus": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string"
+ },
+ "v2KeyVisibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string"
+ },
+ "v2ListImportedAPIKeysResponse": {
+ "properties": {
+ "imported_api_keys": {
+ "items": {
+ "$ref": "#/components/schemas/v2ImportedAPIKey"
+ },
+ "title": "List of imported keys",
+ "type": "array"
+ },
+ "next_page_token": {
+ "title": "Token for fetching the next page (empty if no more results)",
+ "type": "string"
+ }
+ },
+ "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
+ "type": "object"
+ },
+ "v2ListIssuedAPIKeysResponse": {
+ "properties": {
+ "issued_api_keys": {
+ "items": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ },
+ "type": "array"
+ },
+ "next_page_token": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2RateLimitPolicy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2RevocationReason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string"
+ },
+ "v2RotateIssuedAPIKeyResponse": {
+ "properties": {
+ "issued_api_key": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ },
+ "old_issued_api_key": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "secret is the new API key secret (only returned once, never retrievable again)",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2SelfRevokeAPIKeyRequest": {
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "properties": {
+ "credential": {
+ "title": "Full API key secret or imported key (REQUIRED)",
+ "type": "string"
+ },
+ "reason": {
+ "$ref": "#/components/schemas/v2RevocationReason"
+ }
+ },
+ "type": "object"
+ },
+ "v2SelfRevokeAPIKeyResponse": {
+ "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
+ "type": "object"
+ },
+ "v2Token": {
+ "properties": {
+ "claims": {
+ "type": "object"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "token": {
+ "type": "string"
+ }
+ },
+ "title": "Token represents a short-lived derived token (JWT or Macaroon)",
+ "type": "object"
+ },
+ "v2TokenAlgorithm": {
+ "default": "TOKEN_ALGORITHM_UNSPECIFIED",
+ "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
+ "enum": [
+ "TOKEN_ALGORITHM_UNSPECIFIED",
+ "TOKEN_ALGORITHM_JWT",
+ "TOKEN_ALGORITHM_MACAROON"
+ ],
+ "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
+ "type": "string"
+ },
+ "v2VerificationErrorCode": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "v2VerifyAPIKeyRequest": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v2VerifyAPIKeyResponse": {
+ "properties": {
+ "actor_id": {
+ "type": "string"
+ },
+ "error_code": {
+ "$ref": "#/components/schemas/v2VerificationErrorCode"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "is_active": {
+ "type": "boolean"
+ },
+ "issuer": {
+ "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
+ "type": "string"
+ },
+ "key_id": {
+ "type": "string"
+ },
+ "metadata": {
+ "type": "object"
+ },
+ "rate_limit_policy": {
+ "$ref": "#/components/schemas/v2RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "visibility": {
+ "$ref": "#/components/schemas/v2KeyVisibility"
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "info": {
+ "description": "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.\n\nThe API is split into two services:\n\n- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification\n- **SelfService** — self-service revocation for credential holders",
+ "title": "Ory Talos API",
+ "version": "2.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/v2/admin/.well-known/jwks.json": {
+ "get": {
+ "description": "Returns the JSON Web Key Set for token verification. Provides the public\nkeys needed to verify JWT tokens issued by this service. Keys are loaded\nfrom configuration (file://, https://, or base64:// URIs). Follows the\nJWKS standard (RFC 7517).\n\n```http\nGET /v2/admin/.well-known/jwks.json\n```",
+ "operationId": "AdminGetJWKS",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2GetJWKSResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Get JWKS",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/apiKeys/{key_id}:revoke": {
+ "post": {
+ "description": "Immediately revokes an API key (issued or imported). Once revoked, the key\ncan no longer be used for authentication. This operation is irreversible.\nRevoked keys are retained for audit purposes.\n\n```http\nPOST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke\n{\n \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"\n}\n```",
+ "operationId": "AdminRevokeAPIKey",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/StaticCredentialsAdminRevokeAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "API key revoked successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Revoke API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/apiKeys:batchVerify": {
+ "post": {
+ "description": "Verifies multiple credentials in a single request. Efficiently verifies up\nto 100 credentials in parallel. Each credential is verified independently;\npartial failures are returned. Admin access only.\n\n```http\nPOST /v2/admin/apiKeys:batchVerify\n{\n \"requests\": [\n {\"credential\": \"sk_live_abc123...\"},\n {\"credential\": \"eyJhbGciOiJFZERTQSI...\"}\n ]\n}\n```",
+ "operationId": "AdminBatchVerifyAPIKeys",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchVerifyAPIKeysRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchVerifyAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Batch Verify API Keys",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/apiKeys:derive": {
+ "post": {
+ "description": "Mints a short-lived JWT or Macaroon token from an API key. Works with both\nissued and imported keys. The derived token inherits the permissions of the\nparent API key.\n\n```http\nPOST /v2/admin/apiKeys:derive\n{\n \"credential\": \"eyJhbGciOiJFZERTQSI...\",\n \"ttl\": \"1h\"\n}\n```",
+ "operationId": "AdminDeriveToken",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2DeriveTokenRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2DeriveTokenResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Derive Token",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/apiKeys:verify": {
+ "post": {
+ "description": "Verifies a single API key or derived token. Validates the credential's\nsignature, expiration, and revocation status. Works with any credential\ntype (issued keys, imported keys, JWT, macaroon). The verification result\nincludes decoded claims and metadata — admin access only.\n\nCache Control (HTTP Headers):\n - Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup\n - Cache-Control: no-store - Bypasses cache read AND write (never cached)\n - Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)\n\n```http\nPOST /v2/admin/apiKeys:verify\n{\n \"credential\": \"sk_live_abc123...\"\n}\n```",
+ "operationId": "AdminVerifyAPIKey",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Verify API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/importedApiKeys": {
+ "get": {
+ "description": "Lists all imported keys with filtering. Returns imported keys only (not\nissued keys). Supports pagination and AIP-160 filter expressions.\n\n```http\nGET /v2/admin/importedApiKeys?page_size=50\u0026filter=status%3DKEY_STATUS_ACTIVE\n```",
+ "operationId": "AdminListImportedAPIKeys",
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": {
+ "format": "int32",
+ "type": "integer"
+ }
+ },
+ {
+ "description": "Cursor token for pagination (OPTIONAL)",
+ "in": "query",
+ "name": "page_token",
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ListImportedAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "List Imported API Keys",
+ "tags": ["StaticCredentials"]
+ },
+ "post": {
+ "description": "Imports an external API key into the system. Allows importing keys from\nlegacy systems or external providers. The raw key is hashed and stored\nsecurely (HMAC). Imported keys support token derivation (JWT/Macaroon)\nlike issued keys.\n\n```http\nPOST /v2/admin/importedApiKeys\n{\n \"raw_key\": \"sk_live_abc123xyz\",\n \"name\": \"Imported Stripe Key\",\n \"actor_id\": \"user_123\"\n}\n```",
+ "operationId": "AdminImportAPIKey",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ImportAPIKeyRequest"
+ }
+ }
+ },
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ImportAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "API key imported successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Import API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/importedApiKeys/{key_id}": {
+ "delete": {
+ "description": "Permanently deletes an imported key (hard delete). The key is removed from\nthe database. Use RevokeAPIKey for soft deletion (recommended).\n\n```http\nDELETE /v2/admin/importedApiKeys/{key_id}\n```",
+ "operationId": "AdminDeleteImportedAPIKey",
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Imported key deleted successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Delete Imported API Key",
+ "tags": ["StaticCredentials"]
+ },
+ "get": {
+ "description": "Retrieves details about a specific imported key. Returns metadata about\nthe imported key. The original raw key is never returned.\n\n```http\nGET /v2/admin/importedApiKeys/{key_id}\n```",
+ "operationId": "AdminGetImportedAPIKey",
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Get Imported API Key",
+ "tags": ["StaticCredentials"]
+ },
+ "patch": {
+ "description": "Updates metadata, scopes, or rate limits of an imported key. Supports\npartial updates via update_mask (AIP-134).\n\n```http\nPATCH /v2/admin/importedApiKeys/{key_id}\n{\n \"name\": \"New name\",\n \"update_mask\": \"name\"\n}\n```",
+ "operationId": "AdminUpdateImportedAPIKey",
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED, path param)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/StaticCredentialsAdminUpdateImportedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Update Imported API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/importedApiKeys:batchImport": {
+ "post": {
+ "description": "Imports up to 1000 external API keys in one request. Returns per-item\nresults. If at least one item succeeds, response is 200 OK. If all items\nfail, the endpoint returns a non-200 error.\n\n```http\nPOST /v2/admin/importedApiKeys:batchImport\n{\n \"requests\": [\n {\"raw_key\": \"sk_live_abc\", \"name\": \"Stripe key\", \"actor_id\": \"user_1\"},\n {\"raw_key\": \"ghp_xyz\", \"name\": \"GitHub PAT\", \"actor_id\": \"user_2\"}\n ]\n}\n```",
+ "operationId": "AdminBatchImportAPIKeys",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchImportAPIKeysRequest"
+ }
+ }
+ },
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchImportAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Batch import completed. Check per-item results for individual status."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Batch Import API Keys",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/issuedApiKeys": {
+ "get": {
+ "description": "Lists issued API keys with optional filtering. Supports cursor-based\npagination and AIP-160 filter expressions. Returns only issued\n(generated) API keys; use ListImportedAPIKeys for imported keys.\n\n```http\nGET /v2/admin/issuedApiKeys?page_size=50\u0026filter=actor_id%3D%22user_123%22\n```",
+ "operationId": "AdminListIssuedAPIKeys",
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": {
+ "format": "int32",
+ "type": "integer"
+ }
+ },
+ {
+ "description": "Cursor token for pagination",
+ "in": "query",
+ "name": "page_token",
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2ListIssuedAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "List Issued API Keys",
+ "tags": ["StaticCredentials"]
+ },
+ "post": {
+ "description": "Creates a new API key for a given actor. The secret is returned only once\nin the response and cannot be retrieved later. Keys can be scoped with\nspecific permissions and have optional expiration.\n\n```http\nPOST /v2/admin/issuedApiKeys\n{\n \"name\": \"production-service\",\n \"actor_id\": \"user_123\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\"\n}\n```",
+ "operationId": "AdminIssueAPIKey",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2IssueAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2IssueAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "API key issued successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Issue API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/issuedApiKeys/{key_id}": {
+ "get": {
+ "description": "Retrieves details about a specific issued API key including its status,\nscopes, expiration, and usage statistics. The secret is never returned.\n\n```http\nGET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ\n```",
+ "operationId": "AdminGetIssuedAPIKey",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Get Issued API Key",
+ "tags": ["StaticCredentials"]
+ },
+ "patch": {
+ "description": "Updates metadata, scopes, or rate limits of an issued key without rotating\nthe secret. Use RotateIssuedAPIKey to change the secret.\n\n```http\nPATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ\n{\n \"scopes\": [\"read\"],\n \"update_mask\": \"scopes\"\n}\n```",
+ "operationId": "AdminUpdateIssuedAPIKey",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/StaticCredentialsAdminUpdateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Update Issued API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/admin/issuedApiKeys/{key_id}:rotate": {
+ "post": {
+ "description": "Generates a new secret for an issued API key. Creates a new API key with a\nnew key_id and secret, and immediately revokes the old key. This is the\nrecommended way to update scopes, metadata, or rotate credentials.\n\nFor zero-downtime rotation, use this workflow instead:\n 1. IssueAPIKey with new credentials\n 2. Deploy new secret to all services\n 3. Verify new secret works everywhere\n 4. RevokeAPIKey to remove the old key\n\n```http\nPOST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate\n{\n \"scopes\": [\"read\"]\n}\n```",
+ "operationId": "AdminRotateIssuedAPIKey",
+ "parameters": [
+ {
+ "description": "key_id is the ID of the existing API key to rotate",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/StaticCredentialsAdminRotateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2RotateIssuedAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "API key rotated successfully. New key issued, old key revoked."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Rotate Issued API Key",
+ "tags": ["StaticCredentials"]
+ }
+ },
+ "/v2/apiKeys:batchVerify": {
+ "post": {
+ "description": "Verifies multiple credentials in a single request. Efficiently verifies up\nto 100 credentials in parallel. Each credential is verified independently;\npartial failures are returned in the response.\n\n```http\nPOST /v2/apiKeys:batchVerify\n{\n \"requests\": [\n {\"credential\": \"sk_live_abc123...\"},\n {\"credential\": \"sk_live_xyz789...\"}\n ]\n}\n```",
+ "operationId": "BatchVerifyAPIKeys",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchVerifyAPIKeysRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2BatchVerifyAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Batch Verify API Keys",
+ "tags": ["SelfService"]
+ }
+ },
+ "/v2/apiKeys:selfRevoke": {
+ "post": {
+ "description": "Allows an API key holder to revoke their own key. The caller must provide\nthe full API key secret as proof of possession. Supports issued API keys\nand imported keys. JWT and macaroon tokens cannot be self-revoked (they\nare stateless).\n\nThe PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation\n(admin-only).\n\n```http\nPOST /v2/apiKeys:selfRevoke\n{\n \"credential\": \"sk_live_abc123...\",\n \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"\n}\n```",
+ "operationId": "RevokeAPIKey",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2SelfRevokeAPIKeyRequest"
+ }
+ }
+ },
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2SelfRevokeAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Revoke API Key",
+ "tags": ["SelfService"]
+ }
+ },
+ "/v2/apiKeys:verify": {
+ "post": {
+ "description": "Verifies a single credential (API key, JWT, or macaroon). Returns whether\nthe credential is active along with associated metadata. Results are cached\nfor low-latency repeated verifications; use the Cache-Control: no-cache\nheader to bypass the cache.\n\n```http\nPOST /v2/apiKeys:verify\n{\n \"credential\": \"sk_live_abc123...\"\n}\n```",
+ "operationId": "VerifyAPIKey",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ },
+ "summary": "Verify API Key",
+ "tags": ["SelfService"]
+ }
+ }
+ },
+ "tags": [
+ {
+ "description": "Administrative operations for managing static credentials (API keys, personal access tokens, and similar long-lived secrets). Deploy behind authentication and authorization. Supports issued keys (generated by Talos), imported keys (from external systems), and credential verification.",
+ "name": "StaticCredentials"
+ },
+ {
+ "description": "Self-service operations for credential holders. Allows key holders to revoke their own credentials using proof of possession.",
+ "name": "SelfService"
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
index 754acd5f76..ce0b4454cd 100644
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
@@ -1 +1,102 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","properties":{"requests":{"items":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"actor_id":{"title":"Actor identifier (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"title":"Time-to-live for expiration (OPTIONAL)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"},"title":"Keys to import","type":"array"}},"type":"object","title":"v2BatchImportAPIKeysRequest"}}},"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "properties": {
+ "requests": {
+ "items": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "actor_id": {
+ "title": "Actor identifier (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "title": "Time-to-live for expiration (OPTIONAL)",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ },
+ "title": "Keys to import",
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchImportAPIKeysRequest"
+ }
+ }
+ },
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
index 2085ed376a..fc166755fa 100644
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
@@ -1 +1,189 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysResponse returns per-item results and summary counters.","properties":{"failure_count":{"format":"int32","type":"integer"},"results":{"items":{"description":"BatchImportResult contains the result for one key in a batch import request.","properties":{"error_code":{"default":"BATCH_IMPORT_ERROR_UNSPECIFIED","description":"BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import","enum":["BATCH_IMPORT_ERROR_UNSPECIFIED","BATCH_IMPORT_ERROR_INVALID_ARGUMENT","BATCH_IMPORT_ERROR_ALREADY_EXISTS","BATCH_IMPORT_ERROR_FAILED_PRECONDITION","BATCH_IMPORT_ERROR_INTERNAL"],"type":"string","title":"v2BatchImportErrorCode"},"error_message":{"title":"Human-readable failure reason","type":"string"},"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"},"index":{"format":"int32","title":"Zero-based index in request.requests","type":"integer"}},"type":"object","title":"v2BatchImportResult"},"type":"array"},"success_count":{"format":"int32","type":"integer"}},"type":"object","title":"v2BatchImportAPIKeysResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"Batch import completed. Check per-item results for individual status."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
+ "properties": {
+ "failure_count": { "format": "int32", "type": "integer" },
+ "results": {
+ "items": {
+ "description": "BatchImportResult contains the result for one key in a batch import request.",
+ "properties": {
+ "error_code": {
+ "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
+ "enum": [
+ "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
+ "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
+ "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
+ "BATCH_IMPORT_ERROR_INTERNAL"
+ ],
+ "type": "string",
+ "title": "v2BatchImportErrorCode"
+ },
+ "error_message": {
+ "title": "Human-readable failure reason",
+ "type": "string"
+ },
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "create_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_hash": {
+ "title": "SHA-512/256 of credential (for audit)",
+ "type": "string"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ },
+ "index": {
+ "format": "int32",
+ "title": "Zero-based index in request.requests",
+ "type": "integer"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchImportResult"
+ },
+ "type": "array"
+ },
+ "success_count": { "format": "int32", "type": "integer" }
+ },
+ "type": "object",
+ "title": "v2BatchImportAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Batch import completed. Check per-item results for individual status."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
index e99969165b..b92bbf397c 100644
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item
-succeeds, response is 200 OK. If all items fail, the endpoint returns a non-200 error.
+Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item succeeds, response is 200 OK.
+If all items fail, the endpoint returns a non-200 error.
```http
POST /v2/admin/importedApiKeys:batchImport
@@ -47,10 +43,6 @@ POST /v2/admin/importedApiKeys:batchImport
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
index 2a18929b0d..092cc31162 100644
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
index 976062bed3..cd80ba989c 100644
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
@@ -1 +1,36 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"Imported key deleted successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Imported key deleted successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
index d4caeadb6d..a4dd8d7b5f 100644
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Permanently deletes an imported key (hard delete). The key is removed from the database. Use
-RevokeAPIKey for soft deletion (recommended).
+Permanently deletes an imported key (hard delete). The key is removed from the database. Use RevokeAPIKey for soft deletion
+(recommended).
```http
DELETE /v2/admin/importedApiKeys/{key_id}
@@ -39,14 +35,8 @@ DELETE /v2/admin/importedApiKeys/{key_id}
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
index e5cf6fc169..2118789f31 100644
--- a/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
@@ -1 +1,35 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"algorithm":{"default":"TOKEN_ALGORITHM_UNSPECIFIED","description":"- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)","enum":["TOKEN_ALGORITHM_UNSPECIFIED","TOKEN_ALGORITHM_JWT","TOKEN_ALGORITHM_MACAROON"],"title":"TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken","type":"string"},"credential":{"title":"The API key secret (issued or imported) to derive a token from","type":"string"},"custom_claims":{"type":"object"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"type":"string"}},"title":"Token derivation messages","type":"object"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "algorithm": {
+ "default": "TOKEN_ALGORITHM_UNSPECIFIED",
+ "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
+ "enum": [
+ "TOKEN_ALGORITHM_UNSPECIFIED",
+ "TOKEN_ALGORITHM_JWT",
+ "TOKEN_ALGORITHM_MACAROON"
+ ],
+ "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
+ "type": "string"
+ },
+ "credential": {
+ "title": "The API key secret (issued or imported) to derive a token from",
+ "type": "string"
+ },
+ "custom_claims": { "type": "object" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": { "type": "string" }
+ },
+ "title": "Token derivation messages",
+ "type": "object"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
index 4d04bb1508..7b33c4812d 100644
--- a/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
@@ -1 +1,51 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"token":{"properties":{"claims":{"type":"object"},"expire_time":{"format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token":{"type":"string"}},"title":"Token represents a short-lived derived token (JWT or Macaroon)","type":"object"}},"type":"object","title":"v2DeriveTokenResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "token": {
+ "properties": {
+ "claims": { "type": "object" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "token": { "type": "string" }
+ },
+ "title": "Token represents a short-lived derived token (JWT or Macaroon)",
+ "type": "object"
+ }
+ },
+ "type": "object",
+ "title": "v2DeriveTokenResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx b/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
index 9ca1ddf532..be3ae63d56 100644
--- a/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys.
-The derived token inherits the permissions of the parent API key.
+Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys. The derived token inherits
+the permissions of the parent API key.
```http
POST /v2/admin/apiKeys:derive
@@ -45,8 +41,6 @@ POST /v2/admin/apiKeys:derive
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
index 2a18929b0d..092cc31162 100644
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
index ea71e06032..14e67f1c0a 100644
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
@@ -1 +1,129 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_hash": {
+ "title": "SHA-512/256 of credential (for audit)",
+ "type": "string"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
index bbff272645..88cfff5cfe 100644
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
@@ -11,25 +11,20 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Retrieves details about a specific imported key. Returns metadata about the imported key. The
-original raw key is never returned.
+Retrieves details about a specific imported key. Returns metadata about the imported key. The original raw key is never returned.
```http
GET /v2/admin/importedApiKeys/{key_id}
@@ -39,14 +34,8 @@ GET /v2/admin/importedApiKeys/{key_id}
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
index 2be0f6afda..b19b7ceb16 100644
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
@@ -1 +1,10 @@
-{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
index 18d1a6fa3f..9e8b47c392 100644
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
@@ -1 +1,122 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
index 75d0622358..d3bba69188 100644
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Retrieves details about a specific issued API key including its status, scopes, expiration, and
-usage statistics. The secret is never returned.
+Retrieves details about a specific issued API key including its status, scopes, expiration, and usage statistics. The secret is
+never returned.
```http
GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
@@ -39,14 +35,8 @@ GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
index fb99483d78..07c363956d 100644
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
@@ -1 +1,42 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"jwks":{"title":"JSON Web Key Set","type":"object"}},"type":"object","title":"v2GetJWKSResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "jwks": { "title": "JSON Web Key Set", "type": "object" }
+ },
+ "type": "object",
+ "title": "v2GetJWKSResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx b/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
index 1bfefec9bc..b15e7f1d19 100644
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
@@ -11,26 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT
-tokens issued by this service. Keys are loaded from configuration (file://, https://, or base64://
-URIs). Follows the JWKS standard (RFC 7517).
+Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
+Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
```http
GET /v2/admin/derivedKeys/jwks.json
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
index ad5bb8c75f..edad31b034 100644
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
@@ -1 +1,91 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"actor_id":{"title":"Actor identifier (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"title":"Time-to-live for expiration (OPTIONAL)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"}}},"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "actor_id": {
+ "title": "Actor identifier (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "title": "Time-to-live for expiration (OPTIONAL)",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ }
+ }
+ },
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
index ba7473b8df..a9bca0b5a4 100644
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
@@ -1 +1,139 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"}},"type":"object","title":"v2ImportAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key imported successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_hash": {
+ "title": "SHA-512/256 of credential (for audit)",
+ "type": "string"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key imported successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
index 1d93622c48..dca48e4309 100644
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
@@ -11,26 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Imports an external API key into the system. Allows importing keys from legacy systems or external
-providers. The raw key is hashed and stored securely (HMAC). Imported keys support token derivation
-(JWT/Macaroon) like issued keys.
+Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is
+hashed and stored securely (HMAC). Imported keys support token derivation (JWT/Macaroon) like issued keys.
```http
POST /v2/admin/importedApiKeys
@@ -47,8 +42,6 @@ POST /v2/admin/importedApiKeys
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
index f41dd70513..77bac93458 100644
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
@@ -1 +1,69 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssueAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": { "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssueAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
index beec34909c..2bb07c09e5 100644
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
@@ -1 +1,136 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"secret":{"title":"Only returned on creation","type":"string"}},"type":"object","title":"v2IssueAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key issued successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "Only returned on creation",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2IssueAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key issued successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
index 1dbaf5532f..eddb832fa8 100644
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Creates a new API key for a given actor. The secret is returned only once in the response and cannot
-be retrieved later. Keys can be scoped with specific permissions and have optional expiration.
+Creates a new API key for a given actor. The secret is returned only once in the response and cannot be retrieved later. Keys can
+be scoped with specific permissions and have optional expiration.
```http
POST /v2/admin/issuedApiKeys
@@ -47,8 +43,6 @@ POST /v2/admin/issuedApiKeys
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
index 3a777c3e7d..76d4d28b3c 100644
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
@@ -1 +1,22 @@
-{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination (OPTIONAL)","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination (OPTIONAL)",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
index 0739f11bcd..e182533c49 100644
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
@@ -1 +1,149 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_keys":{"items":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_hash":{"title":"SHA-512/256 of credential (for audit)","type":"string"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2ImportedAPIKey"},"title":"List of imported keys","type":"array"},"next_page_token":{"title":"Token for fetching the next page (empty if no more results)","type":"string"}},"title":"ListImportedAPIKeysResponse returns paginated list of imported keys","type":"object"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_keys": {
+ "items": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_hash": {
+ "title": "SHA-512/256 of credential (for audit)",
+ "type": "string"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ },
+ "title": "List of imported keys",
+ "type": "array"
+ },
+ "next_page_token": {
+ "title": "Token for fetching the next page (empty if no more results)",
+ "type": "string"
+ }
+ },
+ "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
+ "type": "object"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
index 25ea9577b5..265ce18dcc 100644
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports
-pagination and AIP-160 filter expressions.
+Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports pagination and AIP-160 filter
+expressions.
```http
GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
@@ -39,14 +35,8 @@ GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
index e8f3ff5027..4a5e5fb847 100644
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
@@ -1 +1,22 @@
-{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
index 70db52232c..5cabad53f6 100644
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
@@ -1 +1,138 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_keys":{"items":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"type":"array"},"next_page_token":{"type":"string"}},"type":"object","title":"v2ListIssuedAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_keys": {
+ "items": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "type": "array"
+ },
+ "next_page_token": { "type": "string" }
+ },
+ "type": "object",
+ "title": "v2ListIssuedAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
index 4c57b15a12..50dd84f74d 100644
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter
-expressions. Returns only issued (generated) API keys; use ListImportedAPIKeys for imported keys.
+Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter expressions. Returns only
+issued (generated) API keys; use ListImportedAPIKeys for imported keys.
```http
GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
@@ -39,14 +35,8 @@ GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
index 2be0f6afda..b19b7ceb16 100644
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
@@ -1 +1,10 @@
-{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
index 9894b96302..fb84fc671f 100644
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
@@ -1 +1,34 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"reason_text":{"title":"Only allowed when reason is PRIVILEGE_WITHDRAWN","type":"string"}},"type":"object","title":"AdminPlaneServiceRevokeAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "reason_text": {
+ "title": "Only allowed when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "AdminPlaneServiceRevokeAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
index f7e1bfaac2..d3cec6dad6 100644
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
@@ -1 +1,36 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"API key revoked successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key revoked successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
index 29a38903e4..0d0a4c219f 100644
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for
-authentication. This operation is irreversible. Revoked keys are retained for audit purposes.
+Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for authentication. This
+operation is irreversible. Revoked keys are retained for audit purposes.
```http
POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
@@ -42,12 +38,8 @@ POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
Request
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
index 05941f5ce6..f832c1b781 100644
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"key_id is the ID of the existing API key to rotate","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "key_id is the ID of the existing API key to rotate",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
index e05311863c..ccf8f9b6f6 100644
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
@@ -1 +1,77 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"title":"metadata for the new API key (inherits from old key if not provided)","type":"object"},"name":{"title":"name for the new API key (inherits from old key if not provided)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"scopes":{"items":{"type":"string"},"title":"scopes for the new API key (inherits from old key if not provided)","type":"array"},"update_mask":{"title":"update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"AdminPlaneServiceRotateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "metadata for the new API key (inherits from old key if not provided)",
+ "type": "object"
+ },
+ "name": {
+ "title": "name for the new API key (inherits from old key if not provided)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "scopes for the new API key (inherits from old key if not provided)",
+ "type": "array"
+ },
+ "update_mask": {
+ "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "AdminPlaneServiceRotateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
index ebb625d466..e7c5a62898 100644
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
@@ -1 +1,223 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"old_issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"},"secret":{"title":"secret is the new API key secret (only returned once, never retrievable again)","type":"string"}},"type":"object","title":"v2RotateIssuedAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key rotated successfully. New key issued, old key revoked."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "old_issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "secret is the new API key secret (only returned once, never retrievable again)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RotateIssuedAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key rotated successfully. New key issued, old key revoked."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
index dff01f94ef..6a0604cc19 100644
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
@@ -11,26 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret,
-and immediately revokes the old key. This is the recommended way to update scopes, metadata, or
-rotate credentials.
+Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret, and immediately revokes the old
+key. This is the recommended way to update scopes, metadata, or rotate credentials.
For zero-downtime rotation, use this workflow instead:
@@ -50,14 +45,8 @@ POST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
index 2be0f6afda..b19b7ceb16 100644
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
@@ -1 +1,10 @@
-{"parameters":[{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
index 5b8eea5f2d..034305392d 100644
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
@@ -1 +1,53 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"type":"string"}},"type":"object","title":"AdminPlaneServiceUpdateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "update_mask": { "type": "string" }
+ },
+ "type": "object",
+ "title": "AdminPlaneServiceUpdateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
index 18d1a6fa3f..9e8b47c392 100644
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
@@ -1 +1,122 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2IPRestriction"},"key_id":{"type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"},"revocation_reason_text":{"title":"Only set when reason is PRIVILEGE_WITHDRAWN","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "revocation_reason_text": {
+ "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
index b3ae207fb6..640939875c 100644
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use
-RotateIssuedAPIKey to change the secret.
+Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedAPIKey to change the
+secret.
```http
PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
@@ -43,14 +39,8 @@ PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
Request
-
+
-
+
-
+
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
index 5630adf675..aaea5e239f 100644
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
@@ -1 +1,30 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"requests":{"items":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2VerifyAPIKeyRequest"},"type":"array"}},"type":"object","title":"v2BatchVerifyAPIKeysRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "requests": {
+ "items": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyRequest"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchVerifyAPIKeysRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
index d9a9bbcc88..3f2a6537e5 100644
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
@@ -1 +1,121 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"key_id":{"type":"string"},"metadata":{"type":"object"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2VerifyAPIKeyResponse"},"type":"array"}},"type":"object","title":"v2BatchVerifyAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "results": {
+ "items": {
+ "properties": {
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyResponse"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchVerifyAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
index ed8ff75c64..59806b1c07 100644
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
+++ b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
@@ -11,25 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in
-parallel. Each credential is verified independently; partial failures are returned.
+Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
+verified independently; partial failures are returned.
```http
POST /v2/admin/apiKeys:batchVerify
@@ -47,10 +43,6 @@ POST /v2/admin/apiKeys:batchVerify
-
+
-
+
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
index 7687389d38..5f67130aa1 100644
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
@@ -1 +1,36 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","properties":{"credential":{"title":"Full API key secret or imported key (REQUIRED)","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2RevocationReason"}},"type":"object","title":"v2SelfRevokeAPIKeyRequest"}}},"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "properties": {
+ "credential": {
+ "title": "Full API key secret or imported key (REQUIRED)",
+ "type": "string"
+ },
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ }
+ },
+ "type": "object",
+ "title": "v2SelfRevokeAPIKeyRequest"
+ }
+ }
+ },
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
index f4b1112ea6..506ca96823 100644
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
@@ -1 +1,40 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success","type":"object","title":"v2SelfRevokeAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
+ "type": "object",
+ "title": "v2SelfRevokeAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
index 38e546e6e8..bdd4dff906 100644
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
@@ -11,26 +11,21 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Allows an API key holder to revoke their own key. The caller must provide the full API key secret as
-proof of possession. Supports issued API keys and imported keys. JWT and macaroon tokens cannot be
-self-revoked (they are stateless).
+Allows an API key holder to revoke their own key. The caller must provide the full API key secret as proof of possession. Supports
+issued API keys and imported keys. JWT and macaroon tokens cannot be self-revoked (they are stateless).
The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
@@ -48,10 +43,6 @@ POST /v2/apiKeys:selfRevoke
-
+
-
+
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
index e6806bb713..b4df248475 100644
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
@@ -1 +1,21 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2VerifyAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
index b2d4010d3e..c7b7c2c7b6 100644
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
@@ -1 +1,109 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"key_id":{"type":"string"},"metadata":{"type":"object"},"actor_id":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2KeyVisibility"}},"type":"object","title":"v2VerifyAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "actor_id": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
index d96c487cdc..48e4e387f7 100644
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
+++ b/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
@@ -11,29 +11,23 @@ info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
+
-Verifies a single API key or derived token. Validates the credential's signature, expiration, and
-revocation status. Works with any credential type (issued keys, imported keys, JWT, macaroon). The
-verification logic automatically detects the credential type.
+Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with
+any credential type (issued keys, imported keys, JWT, macaroon). The verification logic automatically detects the credential type.
-Returns verification result with claims and metadata. Heavily cached for optimal performance
-(typically <1ms).
+Returns verification result with claims and metadata. Heavily cached for optimal performance (typically <1ms).
Cache Control (HTTP Headers):
@@ -56,8 +50,6 @@ POST /v2/admin/apiKeys:verify
-
+
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
index 7648813450..c7988c3cc4 100644
--- a/docs/talos/reference/api/ory-talos-api.info.mdx
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -2,27 +2,25 @@
id: ory-talos-api
title: "Ory Talos API"
description:
- "Ory Talos is a high-performance API key management service. It handles the full credential
- lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
- Macaroon), and revoking access."
+ "Ory Talos is a high-performance API key management service. It handles the full credential lifecycle: issuing keys, verifying
+ them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
sidebar_label: "Ory Talos API"
hide_title: true
custom_edit_url: null
---
-import ApiLogo from "@theme/ApiLogo";
-import Heading from "@theme/Heading";
-import SchemaTabs from "@theme/SchemaTabs";
-import TabItem from "@theme/TabItem";
-import Export from "@theme/ApiExplorer/Export";
+import ApiLogo from "@theme/ApiLogo"
+import Heading from "@theme/Heading"
+import SchemaTabs from "@theme/SchemaTabs"
+import TabItem from "@theme/TabItem"
+import Export from "@theme/ApiExplorer/Export"
-Ory Talos is a high-performance API key management service. It handles the full credential
-lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and
-Macaroon), and revoking access.
+Ory Talos is a high-performance API key management service. It handles the full credential lifecycle: issuing keys, verifying them
+at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
The API is split into two planes:
@@ -31,10 +29,9 @@ The API is split into two planes:
### Quick Links
-- [**Admin Plane**](./admin-plane-service-issue-api-key) — Key lifecycle management (issue, rotate,
- revoke, import, derive tokens, JWKS)
-- [**Data Plane**](./data-plane-service-verify-api-key) — High-performance verification (single,
- batch, self-revoke)
+- [**Admin Plane**](./admin-plane-service-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens,
+ JWKS)
+- [**Data Plane**](./data-plane-service-verify-api-key) — High-performance verification (single, batch, self-revoke)
```mdx-code-block
import DocCardList from '@theme/DocCardList';
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
index 3693bfc24e..f1e07edea7 100644
--- a/docs/talos/reference/api/sidebar.ts
+++ b/docs/talos/reference/api/sidebar.ts
@@ -1,4 +1,4 @@
-import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"
const sidebar: SidebarsConfig = {
apisidebar: [
@@ -115,6 +115,6 @@ const sidebar: SidebarsConfig = {
],
},
],
-};
+}
-export default sidebar.apisidebar;
+export default sidebar.apisidebar
diff --git a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
index 8944c885dc..87cb58eefa 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
@@ -16,8 +16,8 @@ Generate an ECDSA key pair
### Synopsis
-Generate an ECDSA key pair using the specified elliptic curve. Key size is determined by the curve:
-P-256 (256-bit), P-384 (384-bit), P-521 (521-bit). Default curve: P-256.
+Generate an ECDSA key pair using the specified elliptic curve. Key size is determined by the curve: P-256 (256-bit), P-384
+(384-bit), P-521 (521-bit). Default curve: P-256.
```
talos jwk generate ecdsa [flags]
diff --git a/docs/talos/reference/cli/talos-jwk-generate-hmac.md b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
index 3d01d7f0bd..a3555d0ffe 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-hmac.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
@@ -16,8 +16,8 @@ Generate an HMAC secret key
### Synopsis
-Generate a symmetric HMAC secret key. Default size is 512 bits. Minimum is 256 bits. Algorithm is
-determined by key size: 256→HS256, 384→HS384, ≥512→HS512.
+Generate a symmetric HMAC secret key. Default size is 512 bits. Minimum is 256 bits. Algorithm is determined by key size:
+256→HS256, 384→HS384, ≥512→HS512.
```
talos jwk generate hmac [flags]
diff --git a/docs/talos/reference/cli/talos-jwk.md b/docs/talos/reference/cli/talos-jwk.md
index b95eedf0c8..cd67984282 100644
--- a/docs/talos/reference/cli/talos-jwk.md
+++ b/docs/talos/reference/cli/talos-jwk.md
@@ -16,8 +16,8 @@ Generate JSON Web Keys (JWK/JWKS)
### Synopsis
-Generate cryptographic keys in JSON Web Key (JWK) format. Supports EdDSA (Ed25519), ECDSA (P-256,
-P-384, P-521), RSA, and HMAC algorithms.
+Generate cryptographic keys in JSON Web Key (JWK) format. Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC
+algorithms.
### Options
diff --git a/docs/talos/reference/cli/talos-keys-derive-token.md b/docs/talos/reference/cli/talos-keys-derive-token.md
index 7e1eae3fce..2a208b8ea6 100644
--- a/docs/talos/reference/cli/talos-keys-derive-token.md
+++ b/docs/talos/reference/cli/talos-keys-derive-token.md
@@ -16,8 +16,7 @@ Derive a new derived token from an existing API key
### Synopsis
-Derives a new short-lived derived token from an existing opaque API key. The output will be a JWT or
-Macaroon token.
+Derives a new short-lived derived token from an existing opaque API key. The output will be a JWT or Macaroon token.
```
talos keys derive-token [api-key-token] [flags]
diff --git a/docs/talos/reference/cli/talos-keys-imported-batch-import.md b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
index 866d5ea91f..6ffd8296fa 100644
--- a/docs/talos/reference/cli/talos-keys-imported-batch-import.md
+++ b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
@@ -16,8 +16,7 @@ Batch import API keys from a JSON file
### Synopsis
-Batch import API keys from a JSON file. Each request is limited to 1000 keys; the server rejects
-batches that exceed this limit.
+Batch import API keys from a JSON file. Each request is limited to 1000 keys; the server rejects batches that exceed this limit.
```
talos keys imported batch-import --file keys.json [flags]
diff --git a/docs/talos/reference/cli/talos-keys-imported.md b/docs/talos/reference/cli/talos-keys-imported.md
index a33dd97b8c..e79c86e531 100644
--- a/docs/talos/reference/cli/talos-keys-imported.md
+++ b/docs/talos/reference/cli/talos-keys-imported.md
@@ -36,8 +36,7 @@ Import, list, get, revoke, and delete externally-created API keys.
### See also
- [talos keys](talos-keys) Manage API keys
-- [talos keys imported batch-import](talos-keys-imported-batch-import) - Batch import API keys from
- a JSON file
+- [talos keys imported batch-import](talos-keys-imported-batch-import) - Batch import API keys from a JSON file
- [talos keys imported delete](talos-keys-imported-delete) - Permanently delete an imported API key
- [talos keys imported get](talos-keys-imported-get) - Get details of an imported API key
- [talos keys imported import](talos-keys-imported-import) - Import an external API key
diff --git a/docs/talos/reference/cli/talos-keys-issued.md b/docs/talos/reference/cli/talos-keys-issued.md
index b0ada7b6cc..b002b0f525 100644
--- a/docs/talos/reference/cli/talos-keys-issued.md
+++ b/docs/talos/reference/cli/talos-keys-issued.md
@@ -39,6 +39,5 @@ Get, list, update, and rotate issued API keys.
- [talos keys issued get](talos-keys-issued-get) - Get details of an issued API key
- [talos keys issued issue](talos-keys-issued-issue) - Issue a new API key
- [talos keys issued list](talos-keys-issued-list) - List issued API keys
-- [talos keys issued rotate](talos-keys-issued-rotate) - Rotate an issued API key (revokes old key,
- creates new one)
+- [talos keys issued rotate](talos-keys-issued-rotate) - Rotate an issued API key (revokes old key, creates new one)
- [talos keys issued update](talos-keys-issued-update) - Update an issued API key
diff --git a/docs/talos/reference/cli/talos-keys-self-revoke.md b/docs/talos/reference/cli/talos-keys-self-revoke.md
index a8cc6f8f3f..22b72b3e8f 100644
--- a/docs/talos/reference/cli/talos-keys-self-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-self-revoke.md
@@ -16,8 +16,7 @@ Revoke an API key using the credential itself as proof
### Synopsis
-Self-revokes an API key by presenting the full credential as proof of ownership. Does not require
-admin access.
+Self-revokes an API key by presenting the full credential as proof of ownership. Does not require admin access.
```
talos keys self-revoke [credential] [flags]
diff --git a/docs/talos/reference/cli/talos-keys-verify.md b/docs/talos/reference/cli/talos-keys-verify.md
index 3b1e7940ee..2ab4a5443c 100644
--- a/docs/talos/reference/cli/talos-keys-verify.md
+++ b/docs/talos/reference/cli/talos-keys-verify.md
@@ -16,8 +16,7 @@ Verify a credential (API key or token)
### Synopsis
-Verifies a credential against the server. Checks if the credential is active, not expired, and not
-revoked.
+Verifies a credential against the server. Checks if the credential is active, not expired, and not revoked.
```
talos keys verify [credential] [flags]
diff --git a/docs/talos/reference/cli/talos-keys.md b/docs/talos/reference/cli/talos-keys.md
index d1524a60e4..5f0e27a233 100644
--- a/docs/talos/reference/cli/talos-keys.md
+++ b/docs/talos/reference/cli/talos-keys.md
@@ -36,14 +36,11 @@ Create, list, get, revoke, and rotate API keys.
### See also
- [talos](talos) High-performance multi-network API key service
-- [talos keys batch-verify](talos-keys-batch-verify) - Verify multiple credentials in a single
- request
-- [talos keys derive-token](talos-keys-derive-token) - Derive a new derived token from an existing
- API key
+- [talos keys batch-verify](talos-keys-batch-verify) - Verify multiple credentials in a single request
+- [talos keys derive-token](talos-keys-derive-token) - Derive a new derived token from an existing API key
- [talos keys imported](talos-keys-imported) - Manage imported API keys
- [talos keys issue](talos-keys-issue) - Issue a new API key
- [talos keys issued](talos-keys-issued) - Manage issued API keys
- [talos keys revoke](talos-keys-revoke) - Revoke an API key
-- [talos keys self-revoke](talos-keys-self-revoke) - Revoke an API key using the credential itself
- as proof
+- [talos keys self-revoke](talos-keys-self-revoke) - Revoke an API key using the credential itself as proof
- [talos keys verify](talos-keys-verify) - Verify a credential (API key or token)
diff --git a/docs/talos/reference/cli/talos-migrate-down.md b/docs/talos/reference/cli/talos-migrate-down.md
index 8d61c5ac20..b6a04026fb 100644
--- a/docs/talos/reference/cli/talos-migrate-down.md
+++ b/docs/talos/reference/cli/talos-migrate-down.md
@@ -18,8 +18,7 @@ Rollback migrations
Roll back the last N migrations (default: 1).
-This is useful for reverting recent migrations in development. In production, use this carefully and
-ensure you have backups.
+This is useful for reverting recent migrations in development. In production, use this carefully and ensure you have backups.
```
talos migrate down [flags]
diff --git a/docs/talos/reference/cli/talos-migrate-force.md b/docs/talos/reference/cli/talos-migrate-force.md
index ab28e7bce8..1748ac4c57 100644
--- a/docs/talos/reference/cli/talos-migrate-force.md
+++ b/docs/talos/reference/cli/talos-migrate-force.md
@@ -24,8 +24,7 @@ This is useful when:
- You need to manually fix the database state
- You want to mark a migration as applied without running it
-WARNING: This command should be used carefully as it can lead to inconsistent database state if used
-incorrectly.
+WARNING: This command should be used carefully as it can lead to inconsistent database state if used incorrectly.
```
talos migrate force VERSION [flags]
diff --git a/docs/talos/reference/cli/talos-serve-admin.md b/docs/talos/reference/cli/talos-serve-admin.md
index 4172673b4a..9aacdf0819 100644
--- a/docs/talos/reference/cli/talos-serve-admin.md
+++ b/docs/talos/reference/cli/talos-serve-admin.md
@@ -18,8 +18,8 @@ Start the admin plane server (management only)
Starts the admin plane server for API key and network management.
-This mode runs only the management endpoints for administrative operations. It's designed for
-internal tools, CI/CD, and administrative access.
+This mode runs only the management endpoints for administrative operations. It's designed for internal tools, CI/CD, and
+administrative access.
Features:
diff --git a/docs/talos/reference/cli/talos-serve-check.md b/docs/talos/reference/cli/talos-serve-check.md
index 0bb2183449..400bb513ef 100644
--- a/docs/talos/reference/cli/talos-serve-check.md
+++ b/docs/talos/reference/cli/talos-serve-check.md
@@ -18,8 +18,8 @@ Start the data plane server (verification only)
Starts the data plane server for API key and token verification.
-This mode runs only the verification endpoints with caching for optimal read performance. It's
-designed for edge deployments and high-throughput verification workloads.
+This mode runs only the verification endpoints with caching for optimal read performance. It's designed for edge deployments and
+high-throughput verification workloads.
Cache configuration is read from the config file (cache.type, cache.ttl, etc.)
diff --git a/docs/talos/reference/cli/talos.md b/docs/talos/reference/cli/talos.md
index 68f8b42fb8..55ed780892 100644
--- a/docs/talos/reference/cli/talos.md
+++ b/docs/talos/reference/cli/talos.md
@@ -16,8 +16,8 @@ High-performance multi-network API key service
### Synopsis
-API Key Service is a high-performance, multi-network service for managing API keys with support for
-JWT tokens, JWKS, and various cryptographic algorithms.
+API Key Service is a high-performance, multi-network service for managing API keys with support for JWT tokens, JWKS, and various
+cryptographic algorithms.
It provides both admin plane and data plane APIs for comprehensive key management.
diff --git a/docs/talos/reference/config.md b/docs/talos/reference/config.md
index 20b6fca4f2..0d5f7139da 100644
--- a/docs/talos/reference/config.md
+++ b/docs/talos/reference/config.md
@@ -5,27 +5,25 @@ description: Auto-generated configuration reference from JSON Schema
# Configuration reference
-This page is auto-generated from the
-[configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
+This page is auto-generated from the [configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
Required top-level keys: `credentials`, `secrets`
## Environment variables
-Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and
-converts dot-separated config paths to uppercase with underscores:
+Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and converts dot-separated config
+paths to uppercase with underscores:
```
TALOS__
```
-Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port`
-becomes `TALOS_SERVE_HTTP_PORT`.
+Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port` becomes
+`TALOS_SERVE_HTTP_PORT`.
### Array values
-For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed
-variables:
+For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed variables:
```bash
# Comma-separated
diff --git a/docs/talos/reference/error-codes.md b/docs/talos/reference/error-codes.md
index 532765e224..e17b22d3d1 100644
--- a/docs/talos/reference/error-codes.md
+++ b/docs/talos/reference/error-codes.md
@@ -8,9 +8,8 @@ description: HTTP and gRPC error codes returned by the Talos API
# Error codes
-Talos returns structured error responses following the [herodot](https://github.com/ory/herodot)
-error format. Every error response includes an `id`, HTTP status code, status text, and a
-human-readable message.
+Talos returns structured error responses following the [herodot](https://github.com/ory/herodot) error format. Every error
+response includes an `id`, HTTP status code, status text, and a human-readable message.
## Error response format
@@ -97,5 +96,4 @@ The `BatchImportAPIKeys` response includes per-item error codes:
- **4xx errors**: Fix the request and retry. Do not retry without changes.
- **409 Conflict**: Check if the resource already exists or is in an incompatible state.
- **5xx errors**: Retry with exponential backoff and jitter.
-- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After`
- header value if present.
+- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After` header value if present.
diff --git a/docs/talos/reference/events.md b/docs/talos/reference/events.md
index 26b5d8751d..53c89a63c2 100644
--- a/docs/talos/reference/events.md
+++ b/docs/talos/reference/events.md
@@ -8,12 +8,10 @@ description: Structured audit events emitted by Talos via OpenTelemetry
# Audit events
-Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle
-operations. Events are attached to the active OTEL span and forwarded to any configured OTEL
-collector. They are never persisted locally.
+Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle operations. Events are attached to
+the active OTEL span and forwarded to any configured OTEL collector. They are never persisted locally.
-Each event carries a set of structured attributes that provide context about the operation, the
-actor, and the affected resource.
+Each event carries a set of structured attributes that provide context about the operation, the actor, and the affected resource.
## Event types
@@ -50,9 +48,9 @@ Each event carries the following OTEL span event attributes:
## Dynamic metadata attributes
-The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys
-are prefixed with `metadata.` in OTEL attributes. For example, a metadata entry
-`{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with value `jwt`.
+The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys are prefixed with `metadata.`
+in OTEL attributes. For example, a metadata entry `{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with
+value `jwt`.
Metadata is optional and varies by event type. Common metadata keys include:
@@ -75,5 +73,4 @@ events.New(events.EventAPIKeyCreated).
Emit(ctx, emitter)
```
-Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently
-dropped.
+Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently dropped.
diff --git a/docs/talos/reference/token-format.md b/docs/talos/reference/token-format.md
index 7788928497..9110855fb7 100644
--- a/docs/talos/reference/token-format.md
+++ b/docs/talos/reference/token-format.md
@@ -37,9 +37,8 @@ The identifier is a Base58 encoding of `timestamp:uuid`:
- **Timestamp**: Unix epoch seconds (int64). Embedded at key creation time.
- **UUID**: UUID v4 (36 chars with hyphens). Used as the `key_id` for database lookup.
-Base58 encoding uses the Bitcoin alphabet
-(`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually ambiguous
-characters (`0`, `O`, `I`, `l`).
+Base58 encoding uses the Bitcoin alphabet (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually
+ambiguous characters (`0`, `O`, `I`, `l`).
### Checksum verification
@@ -49,8 +48,8 @@ The checksum is computed over the payload `prefix_v1_identifier_`:
2. Truncate to 64 bits
3. Base58-encode the result
-During verification, all configured secrets (current + retired) are tried in order. This supports
-secret rotation without invalidating existing keys.
+During verification, all configured secrets (current + retired) are tried in order. This supports secret rotation without
+invalidating existing keys.
### Credential routing
@@ -65,8 +64,7 @@ When a credential is submitted for verification, Talos identifies the credential
## Imported key format
-Imported keys have no format requirements. Any string credential can be imported. Talos stores a
-tenant-scoped hash:
+Imported keys have no format requirements. Any string credential can be imported. Talos stores a tenant-scoped hash:
```
SHA-512/256(network_id + 0x00 + raw_key)
@@ -84,8 +82,8 @@ Derived tokens produced as JWTs follow the standard JWT format:
eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature
```
-Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm
-is determined by the `alg` field in the JWK (EdDSA or RS256).
+Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm is determined by the `alg`
+field in the JWK (EdDSA or RS256).
### Macaroon
@@ -95,8 +93,8 @@ Macaroon tokens use a configurable prefix:
_v1_
```
-The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`).
-The data section contains the macaroon identifier and signature.
+The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`). The data section contains the
+macaroon identifier and signature.
## ID formats
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index cf5410e324..478e027d7d 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -3,6 +3,7 @@
import type { Config } from "@docusaurus/types"
import type * as Preset from "@docusaurus/preset-classic"
+import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"
import lightTheme from "./src/utils/prismLight.mjs"
import darkTheme from "./src/utils/prismDark.mjs"
@@ -175,6 +176,21 @@ const config: Config = {
disableVersioning: false,
include: ["**/*.md", "**/*.mdx", "**/*.jsx", "**/*.tsx"],
docRootComponent: "@theme/DocRoot",
+ docItemComponent: "@theme/ApiItem",
+ },
+ ],
+ [
+ "docusaurus-plugin-openapi-docs",
+ {
+ id: "openapi",
+ docsPluginId: "default",
+ config: {
+ talos: {
+ specPath: "docs/talos/reference/api.json",
+ outputDir: "docs/talos/reference/api",
+ sidebarOptions: { groupPathsBy: "tag" },
+ } satisfies OpenApiPlugin.Options,
+ },
},
],
"@docusaurus/plugin-content-pages",
diff --git a/src/sidebar.ts b/src/sidebar.ts
index f55a41c1d9..5527733ed3 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -5,7 +5,7 @@ import {
SidebarItem,
SidebarItemConfig,
} from "@docusaurus/plugin-content-docs/src/sidebars/types"
-import apiSidebar from "../docs/talos/reference/api/sidebar";
+import apiSidebar from "../docs/talos/reference/api/sidebar"
type SidebarItemsConfig = SidebarItemConfig[]
@@ -918,129 +918,129 @@ const keto: SidebarItemsConfig = [
},
]
-const talos: SidebarItemsConfig = [
- {
- type: "doc",
- id: "talos/index",
- label: "Home",
- },
- {
- type: "category",
- label: "Quickstart",
- collapsed: false,
- link: { type: "doc", id: "talos/quickstart/index" },
- items: ["talos/quickstart/docker-commercial"],
- },
- {
- type: "category",
- label: "talos/integrate",
- collapsed: false,
- link: { type: "doc", id: "talos/integrate/index" },
- items: [
- "talos/integrate/issue-and-verify",
- "talos/integrate/import-keys",
- "talos/integrate/derive-tokens",
- "talos/integrate/batch-operations",
- "talos/integrate/key-lifecycle",
- "talos/integrate/self-revocation",
- "talos/integrate/ip-restrictions",
- "talos/integrate/rate-limiting",
- "talos/integrate/error-handling",
- {
- type: "category",
- label: "SDK",
- items: ["talos/integrate/sdk/go", "talos/integrate/sdk/curl"],
- },
- ],
- },
- {
- type: "category",
- label: "talos/operate",
- collapsed: false,
- link: { type: "doc", id: "talos/operate/index" },
- items: [
- "talos/operate/install",
- "talos/operate/configure",
- {
- type: "category",
- label: "Database",
- link: { type: "doc", id: "talos/operate/database/index" },
- items: [
- "talos/operate/database/sqlite",
- "talos/operate/database/postgresql",
- "talos/operate/database/mysql",
- "talos/operate/database/cockroachdb",
- "talos/operate/database/migrations",
- ],
- },
- {
- type: "category",
- label: "Deploy",
- link: { type: "doc", id: "talos/operate/deploy/index" },
- items: [
- "talos/operate/deploy/docker",
- "talos/operate/deploy/kubernetes",
- "talos/operate/deploy/separate-planes",
- "talos/operate/deploy/edge-proxy",
- ],
- },
- "talos/operate/secrets",
- "talos/operate/tls",
- {
- type: "category",
- label: "Monitoring",
- link: { type: "doc", id: "talos/operate/monitoring/index" },
- items: [
- "talos/operate/monitoring/metrics",
- "talos/operate/monitoring/tracing",
- "talos/operate/monitoring/health-checks",
- ],
- },
- {
- type: "category",
- label: "Cache",
- link: { type: "doc", id: "talos/operate/cache/index" },
- items: ["talos/operate/cache/memory", "talos/operate/cache/redis"],
- },
- "talos/operate/multi-tenancy",
- "talos/operate/troubleshooting",
- "talos/operate/security-hardening",
- ],
- },
- {
- type: "category",
- label: "Concepts",
- collapsed: true,
- link: { type: "doc", id: "talos/concepts/index" },
- items: [
- "talos/concepts/architecture",
- "talos/concepts/credential-types",
- "talos/concepts/token-format",
- "talos/concepts/security-model",
- "talos/concepts/ip-restrictions",
- "talos/concepts/caching",
- "talos/concepts/rate-limiting",
- "talos/concepts/token-derivation-security",
- ],
- },
- {
- type: "category",
- label: "Reference",
- collapsed: true,
- link: { type: "doc", id: "talos/reference/index" },
- items: [
- {
- type: "category",
- label: "API",
- link: { type: "doc", id: "talos/reference/api/ory-talos-api" },
- items: apiSidebar,
- },
- "talos/reference/config",
- "talos/reference/error-codes",
- "talos/reference/token-format",
- ],
- },
- ]
+const talos: SidebarItemsConfig = [
+ {
+ type: "doc",
+ id: "talos/index",
+ label: "Home",
+ },
+ {
+ type: "category",
+ label: "Quickstart",
+ collapsed: false,
+ link: { type: "doc", id: "talos/quickstart/index" },
+ items: ["talos/quickstart/docker-commercial"],
+ },
+ {
+ type: "category",
+ label: "talos/integrate",
+ collapsed: false,
+ link: { type: "doc", id: "talos/integrate/index" },
+ items: [
+ "talos/integrate/issue-and-verify",
+ "talos/integrate/import-keys",
+ "talos/integrate/derive-tokens",
+ "talos/integrate/batch-operations",
+ "talos/integrate/key-lifecycle",
+ "talos/integrate/self-revocation",
+ "talos/integrate/ip-restrictions",
+ "talos/integrate/rate-limiting",
+ "talos/integrate/error-handling",
+ {
+ type: "category",
+ label: "SDK",
+ items: ["talos/integrate/sdk/go", "talos/integrate/sdk/curl"],
+ },
+ ],
+ },
+ {
+ type: "category",
+ label: "talos/operate",
+ collapsed: false,
+ link: { type: "doc", id: "talos/operate/index" },
+ items: [
+ "talos/operate/install",
+ "talos/operate/configure",
+ {
+ type: "category",
+ label: "Database",
+ link: { type: "doc", id: "talos/operate/database/index" },
+ items: [
+ "talos/operate/database/sqlite",
+ "talos/operate/database/postgresql",
+ "talos/operate/database/mysql",
+ "talos/operate/database/cockroachdb",
+ "talos/operate/database/migrations",
+ ],
+ },
+ {
+ type: "category",
+ label: "Deploy",
+ link: { type: "doc", id: "talos/operate/deploy/index" },
+ items: [
+ "talos/operate/deploy/docker",
+ "talos/operate/deploy/kubernetes",
+ "talos/operate/deploy/separate-planes",
+ "talos/operate/deploy/edge-proxy",
+ ],
+ },
+ "talos/operate/secrets",
+ "talos/operate/tls",
+ {
+ type: "category",
+ label: "Monitoring",
+ link: { type: "doc", id: "talos/operate/monitoring/index" },
+ items: [
+ "talos/operate/monitoring/metrics",
+ "talos/operate/monitoring/tracing",
+ "talos/operate/monitoring/health-checks",
+ ],
+ },
+ {
+ type: "category",
+ label: "Cache",
+ link: { type: "doc", id: "talos/operate/cache/index" },
+ items: ["talos/operate/cache/memory", "talos/operate/cache/redis"],
+ },
+ "talos/operate/multi-tenancy",
+ "talos/operate/troubleshooting",
+ "talos/operate/security-hardening",
+ ],
+ },
+ {
+ type: "category",
+ label: "Concepts",
+ collapsed: true,
+ link: { type: "doc", id: "talos/concepts/index" },
+ items: [
+ "talos/concepts/architecture",
+ "talos/concepts/credential-types",
+ "talos/concepts/token-format",
+ "talos/concepts/security-model",
+ "talos/concepts/ip-restrictions",
+ "talos/concepts/caching",
+ "talos/concepts/rate-limiting",
+ "talos/concepts/token-derivation-security",
+ ],
+ },
+ {
+ type: "category",
+ label: "Reference",
+ collapsed: true,
+ link: { type: "doc", id: "talos/reference/index" },
+ items: [
+ {
+ type: "category",
+ label: "API",
+ link: { type: "doc", id: "talos/reference/api/ory-talos-api" },
+ items: apiSidebar,
+ },
+ "talos/reference/config",
+ "talos/reference/error-codes",
+ "talos/reference/token-format",
+ ],
+ },
+]
const polis: SidebarItemsConfig = [
homeLink,
From d42ba691c2a85275ff7610b8c27f57ca654a2082 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Mon, 27 Apr 2026 12:39:36 +0200
Subject: [PATCH 3/8] chore: synchronize workspaces
---
docs/talos/CLAUDE.md | 10 +-
docs/talos/index.md | 1 +
docs/talos/integrate/batch-operations.md | 4 +-
docs/talos/integrate/derive-tokens.md | 4 +-
docs/talos/integrate/import-keys.md | 6 +-
docs/talos/integrate/ip-restrictions.md | 8 +-
docs/talos/integrate/issue-and-verify.md | 9 +-
docs/talos/integrate/key-lifecycle.md | 6 +-
docs/talos/integrate/rate-limiting.md | 6 +-
docs/talos/integrate/self-revocation.md | 2 +-
docs/talos/quickstart/preview.md | 358 ++++++++++++++++++
...n-batch-import-api-keys.RequestSchema.json | 102 +++++
...min-batch-import-api-keys.StatusCodes.json | 185 +++++++++
.../api/admin-batch-import-api-keys.api.mdx | 48 +++
...n-batch-verify-api-keys.RequestSchema.json | 30 ++
...min-batch-verify-api-keys.StatusCodes.json | 125 ++++++
.../api/admin-batch-verify-api-keys.api.mdx | 48 +++
...delete-imported-api-key.ParamsDetails.json | 11 +
...delete-imported-api-key.RequestSchema.json | 1 +
...n-delete-imported-api-key.StatusCodes.json | 36 ++
.../api/admin-delete-imported-api-key.api.mdx | 42 ++
.../api/admin-derive-token.RequestSchema.json | 38 ++
.../api/admin-derive-token.StatusCodes.json | 51 +++
.../reference/api/admin-derive-token.api.mdx | 46 +++
...in-get-imported-api-key.ParamsDetails.json | 11 +
...in-get-imported-api-key.RequestSchema.json | 1 +
...dmin-get-imported-api-key.StatusCodes.json | 125 ++++++
.../api/admin-get-imported-api-key.api.mdx | 41 ++
...dmin-get-issued-api-key.ParamsDetails.json | 10 +
...dmin-get-issued-api-key.RequestSchema.json | 1 +
.../admin-get-issued-api-key.StatusCodes.json | 122 ++++++
.../api/admin-get-issued-api-key.api.mdx | 42 ++
.../api/admin-get-jwks.RequestSchema.json | 1 +
.../api/admin-get-jwks.StatusCodes.json | 42 ++
.../reference/api/admin-get-jwks.api.mdx | 38 ++
.../admin-import-api-key.RequestSchema.json | 91 +++++
.../api/admin-import-api-key.StatusCodes.json | 135 +++++++
.../api/admin-import-api-key.api.mdx | 47 +++
.../admin-issue-api-key.RequestSchema.json | 72 ++++
.../api/admin-issue-api-key.StatusCodes.json | 136 +++++++
.../reference/api/admin-issue-api-key.api.mdx | 48 +++
...-list-imported-api-keys.ParamsDetails.json | 22 ++
...-list-imported-api-keys.RequestSchema.json | 1 +
...in-list-imported-api-keys.StatusCodes.json | 145 +++++++
.../api/admin-list-imported-api-keys.api.mdx | 42 ++
...in-list-issued-api-keys.ParamsDetails.json | 22 ++
...in-list-issued-api-keys.RequestSchema.json | 1 +
...dmin-list-issued-api-keys.StatusCodes.json | 138 +++++++
.../api/admin-list-issued-api-keys.api.mdx | 42 ++
.../admin-revoke-api-key.ParamsDetails.json | 10 +
.../admin-revoke-api-key.RequestSchema.json | 34 ++
.../api/admin-revoke-api-key.StatusCodes.json | 36 ++
.../api/admin-revoke-api-key.api.mdx | 45 +++
...n-rotate-issued-api-key.ParamsDetails.json | 11 +
...n-rotate-issued-api-key.RequestSchema.json | 77 ++++
...min-rotate-issued-api-key.StatusCodes.json | 223 +++++++++++
.../api/admin-rotate-issued-api-key.api.mdx | 52 +++
...update-imported-api-key.ParamsDetails.json | 11 +
...update-imported-api-key.RequestSchema.json | 56 +++
...n-update-imported-api-key.StatusCodes.json | 125 ++++++
.../api/admin-update-imported-api-key.api.mdx | 45 +++
...n-update-issued-api-key.ParamsDetails.json | 10 +
...n-update-issued-api-key.RequestSchema.json | 53 +++
...min-update-issued-api-key.StatusCodes.json | 122 ++++++
.../api/admin-update-issued-api-key.api.mdx | 46 +++
.../admin-verify-api-key.RequestSchema.json | 21 +
.../api/admin-verify-api-key.StatusCodes.json | 113 ++++++
.../api/admin-verify-api-key.api.mdx | 52 +++
.../reference/api/ory-talos-api.info.mdx | 19 +-
.../api/revoke-api-key.RequestSchema.json | 36 ++
.../api/revoke-api-key.StatusCodes.json | 40 ++
.../reference/api/revoke-api-key.api.mdx | 48 +++
docs/talos/reference/api/sidebar.ts | 72 ++--
docs/talos/reference/config.md | 32 +-
74 files changed, 3854 insertions(+), 88 deletions(-)
create mode 100644 docs/talos/quickstart/preview.md
create mode 100644 docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-derive-token.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-derive-token.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-derive-token.api.mdx
create mode 100644 docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-get-imported-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-get-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-get-jwks.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-get-jwks.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-get-jwks.api.mdx
create mode 100644 docs/talos/reference/api/admin-import-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-import-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-import-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-issue-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
create mode 100644 docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-revoke-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-update-imported-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
create mode 100644 docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-update-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/admin-verify-api-key.api.mdx
create mode 100644 docs/talos/reference/api/revoke-api-key.RequestSchema.json
create mode 100644 docs/talos/reference/api/revoke-api-key.StatusCodes.json
create mode 100644 docs/talos/reference/api/revoke-api-key.api.mdx
diff --git a/docs/talos/CLAUDE.md b/docs/talos/CLAUDE.md
index 96b425ab9d..b69f422175 100644
--- a/docs/talos/CLAUDE.md
+++ b/docs/talos/CLAUDE.md
@@ -55,25 +55,25 @@ in the canonical references:
or links without a file extension. Hashbang anchors are allowed after the file extension.
- Links to `.md` files: `[text](../reference/error-codes.md#section)`
-- Links to `.api.mdx` files: `[text](../reference/api/admin-plane-service-issue-api-key.api.mdx)`
+- Links to `.api.mdx` files: `[text](../reference/api/admin-issue-api-key.api.mdx)`
- Links to directory index pages: `[text](../operate/cache/index.md)` (never `../operate/cache/`)
- Links within the same directory: `[text](./sibling-page.md)`
```text
# Good: relative links with file extensions
-For the complete field reference, see the [IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+For the complete field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
For the full list of error codes, see the [error codes reference](../reference/error-codes.md#verification-error-codes).
# Bad: absolute links without file extensions
-For the complete field reference, see the [IssueAPIKey API reference](/reference/api/admin-plane-service-issue-api-key).
+For the complete field reference, see the [IssueAPIKey API reference](/reference/api/admin-issue-api-key).
For the full list of error codes, see the [error codes reference](/reference/error-codes#verification-error-codes).
```
### API reference URL pattern
-API reference pages are `.api.mdx` files at `reference/api/{service}-{method}.api.mdx` where:
+API reference pages are `.api.mdx` files at `reference/api/{plane}-{method}.api.mdx` where:
-- `{service}` is `admin-plane-service` or `data-plane-service`
+- `{plane}` is `admin` or `data`
- `{method}` is the kebab-case method name (e.g., `issue-api-key`, `verify-api-key`)
The API overview page is `reference/api/ory-talos-api.info.mdx`.
diff --git a/docs/talos/index.md b/docs/talos/index.md
index 5eea36a67f..34c67b0ef9 100644
--- a/docs/talos/index.md
+++ b/docs/talos/index.md
@@ -1,5 +1,6 @@
---
title: Ory Talos
+slug: /
---
# Ory Talos
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.md
index cf65e27a12..4dd4bcee13 100644
--- a/docs/talos/integrate/batch-operations.md
+++ b/docs/talos/integrate/batch-operations.md
@@ -149,8 +149,8 @@ response is `200 OK` if at least one key succeeds. Check `failure_count` and ind
failures.
For the complete field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx). For batch import error
-codes, see the [error codes reference](../reference/error-codes.md#batch-import-error-codes).
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
+[error codes reference](../reference/error-codes.md#batch-import-error-codes).
### Limits
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.md
index 8f8ba8d7a2..5d36301868 100644
--- a/docs/talos/integrate/derive-tokens.md
+++ b/docs/talos/integrate/derive-tokens.md
@@ -105,13 +105,13 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or `TOKEN_ALGORITHM_MACAROON`),
optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For the complete field reference, see the
-[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
+[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
### Response
The response contains a `token` object with `token.token` (the derived token string), `token.expire_time`, `token.scopes`, and
`token.claims`. For the complete field reference, see the
-[DeriveToken API reference](../reference/api/admin-plane-service-derive-token.api.mdx).
+[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
## Verify a derived token
diff --git a/docs/talos/integrate/import-keys.md b/docs/talos/integrate/import-keys.md
index 4b61fdf450..064a84a73c 100644
--- a/docs/talos/integrate/import-keys.md
+++ b/docs/talos/integrate/import-keys.md
@@ -72,7 +72,7 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`, `ttl`, and `metadata`. For
-the complete field reference, see the [ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
+the complete field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
The response returns an `imported_api_key` object. The `raw_key` is **never returned** after import.
@@ -142,8 +142,8 @@ The response includes a `results` array with per-item outcomes (`imported_api_ke
failure), plus `success_count` and `failure_count` counters. If at least one key succeeds, the HTTP response is `200 OK`.
For the complete response field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-plane-service-batch-import-api-keys.api.mdx). For batch import error
-codes, see the [error codes reference](../reference/error-codes.md#batch-import-error-codes).
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
+[error codes reference](../reference/error-codes.md#batch-import-error-codes).
## List imported keys
diff --git a/docs/talos/integrate/ip-restrictions.md b/docs/talos/integrate/ip-restrictions.md
index cb215b1eb0..bf82d23317 100644
--- a/docs/talos/integrate/ip-restrictions.md
+++ b/docs/talos/integrate/ip-restrictions.md
@@ -90,8 +90,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
-For the complete request field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+For the complete request field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify from an allowed IP
@@ -195,7 +194,7 @@ echo "$UNRESTRICT_RESPONSE" | jq .
For the complete update field reference, see the
-[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Import keys with IP restrictions
@@ -235,8 +234,7 @@ echo "$IMPORT_RESPONSE" | jq .
-For the complete import field reference, see the
-[ImportAPIKey API reference](../reference/api/admin-plane-service-import-api-key.api.mdx).
+For the complete import field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
## Behavior notes
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.md
index adb31f47d7..c9be80a77d 100644
--- a/docs/talos/integrate/issue-and-verify.md
+++ b/docs/talos/integrate/issue-and-verify.md
@@ -73,7 +73,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`, `ttl`, `metadata`, and
`rate_limit_policy`. For the complete field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
### Response fields
@@ -83,8 +83,7 @@ The response contains two top-level fields:
- **`secret`** — The full API key credential. This value is returned **only once** and cannot be retrieved later. Store it
securely.
-For the complete metadata field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+For the complete metadata field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a key
@@ -116,7 +115,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
The response includes `is_active` (boolean), `key_id`, `actor_id`, `scopes`, `metadata`, and `expire_time` when valid. When
`is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled (Commercial),
the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the complete
-field reference, see the [VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+field reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
### Verification error codes
@@ -195,7 +194,7 @@ curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
### Query parameters
Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status` (filtering). For the complete
-parameter reference, see the [ListIssuedAPIKeys API reference](../reference/api/admin-plane-service-list-issued-api-keys.api.mdx).
+parameter reference, see the [ListIssuedAPIKeys API reference](../reference/api/admin-list-issued-api-keys.api.mdx).
The response includes a `next_page_token` field. When empty, you have reached the last page.
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.md
index 8239f6a79f..85cd392e64 100644
--- a/docs/talos/integrate/key-lifecycle.md
+++ b/docs/talos/integrate/key-lifecycle.md
@@ -95,7 +95,7 @@ The `update_mask` field controls which fields are modified. Only fields listed i
[AIP-134](https://google.aip.dev/134) standard for partial updates.
Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
-[UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Rotate a key
@@ -146,7 +146,7 @@ echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once), and `old_issued_api_key`
(status `KEY_STATUS_REVOKED`). For the complete field reference, see the
-[RotateIssuedAPIKey API reference](../reference/api/admin-plane-service-rotate-issued-api-key.api.mdx).
+[RotateIssuedAPIKey API reference](../reference/api/admin-rotate-issued-api-key.api.mdx).
### Zero-downtime rotation
@@ -188,7 +188,7 @@ echo "Key revoked"
Standard reasons include `REVOCATION_REASON_KEY_COMPROMISE`, `REVOCATION_REASON_SUPERSEDED`,
`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only). For the complete list, see the
-[RevokeAPIKey API reference](../reference/api/admin-plane-service-revoke-api-key.api.mdx).
+[RevokeAPIKey API reference](../reference/api/admin-revoke-api-key.api.mdx).
When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable explanation.
diff --git a/docs/talos/integrate/rate-limiting.md b/docs/talos/integrate/rate-limiting.md
index 20aef9f956..fe2a8c979d 100644
--- a/docs/talos/integrate/rate-limiting.md
+++ b/docs/talos/integrate/rate-limiting.md
@@ -71,7 +71,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
The response includes the full key metadata with the `rate_limit_policy` attached. For the complete request and response field
-reference, see the [IssueAPIKey API reference](../reference/api/admin-plane-service-issue-api-key.api.mdx).
+reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a rate-limited key
@@ -98,7 +98,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining` (approximate requests available
before the limit is reached) and `rate_limit_reset_time` (when full capacity is recovered). For the complete response field
-reference, see the [VerifyAPIKey API reference](../reference/api/data-plane-service-verify-api-key.api.mdx).
+reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
## Exceeding the limit
@@ -152,7 +152,7 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
The updated policy takes effect on the next verification request (subject to cache TTL). For the complete update field reference,
-see the [UpdateIssuedAPIKey API reference](../reference/api/admin-plane-service-update-issued-api-key.api.mdx).
+see the [UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Remove rate limit policy
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.md
index 050618b116..7413439c14 100644
--- a/docs/talos/integrate/self-revocation.md
+++ b/docs/talos/integrate/self-revocation.md
@@ -125,7 +125,7 @@ fi
The request requires `credential` (the full API key secret) and optionally `reason` (revocation reason enum). For the complete
-field reference, see the [SelfRevokeAPIKey API reference](../reference/api/data-plane-service-self-revoke-api-key.api.mdx).
+field reference, see the [SelfRevokeAPIKey API reference](../reference/api/revoke-api-key.api.mdx).
Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are stateless and cannot be revoked.
All revocation reasons except `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
diff --git a/docs/talos/quickstart/preview.md b/docs/talos/quickstart/preview.md
new file mode 100644
index 0000000000..5306920604
--- /dev/null
+++ b/docs/talos/quickstart/preview.md
@@ -0,0 +1,358 @@
+---
+title: Early-access quickstart
+---
+
+```mdx-code-block
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+```
+
+# Early-access quickstart
+
+Ory Talos is Ory's API key management service. This guide shows how to pull the public early-access
+commercial image, start a local Postgres-backed Ory Talos instance, and run the headline flows for
+issued and imported API keys. You only need Docker for the bring-up steps below; the `curl`
+examples are the preview baseline, and the Talos CLI is shown as an optional alternative.
+
+## Pull the image
+
+```bash
+docker pull europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6
+```
+
+## Start Postgres
+
+```bash
+docker network create talos-preview
+docker run -d --name talos-postgres --network talos-preview \
+ -e POSTGRES_USER=talos -e POSTGRES_PASSWORD=talos -e POSTGRES_DB=talos \
+ -p 5432:5432 postgres:16-alpine
+```
+
+## Configure Talos
+
+Create `config.yaml` in your working directory:
+
+```yaml
+serve:
+ http: { host: "0.0.0.0", port: 8080 }
+ metrics: { host: "0.0.0.0", port: 4422 }
+
+credentials:
+ issuer: "http://localhost:8080"
+ api_keys:
+ default_ttl: "720h"
+ prefix: { current: "talos" }
+ derived_tokens:
+ default_ttl: "1h"
+ jwt:
+ algorithm: "EdDSA"
+ signing_keys:
+ urls:
+ - "base64://eyAgImtleXMiOiBbICAgIHsgICAgICAiYWxnIjogIkVkRFNBIiwgICAgICAiY3J2IjogIkVkMjU1MTkiLCAgICAgICJkIjogIjl3VTNfV3p0dmx3TXg0SGlfN2dsSVduY09XNlVIR2I5amxDdDZEZkVGa2MiLCAgICAgICJraWQiOiAiZG9ja2VyLWRldi0wMDEiLCAgICAgICJrdHkiOiAiT0tQIiwgICAgICAidXNlIjogInNpZyIsICAgICAgIngiOiAiNGtTQTdtNU5jYnFDUC1mZk9fNGhQM2tsNHB0NGctLTNRQ21zQmwzb05lVSIgICAgfSAgXX0="
+ macaroon:
+ prefix: { current: "mc" }
+
+db:
+ dsn: "postgres://talos:talos@talos-postgres:5432/talos?sslmode=disable"
+
+secrets:
+ default: { current: "preview-default-secret-minimum-32-chars-long" }
+ hmac: { current: "preview-hmac-secret-minimum-32-chars-long" }
+ pagination: { current: "preview-pagination-secret-32-chars-min" }
+
+cache: { type: "memory", ttl: "5m" }
+multitenancy: { enabled: false }
+log: { level: "info", format: "json" }
+```
+
+:::caution
+
+This config embeds the development EdDSA JWK from `deployments/docker/config/config.yaml`. Replace
+it before any non-preview use because the private key is published in the source tree.
+
+:::
+
+## Run database migrations
+
+Initialize the Postgres schema before the first server start:
+
+```bash
+docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ migrate up --database "postgres://talos:talos@talos-postgres:5432/talos?sslmode=disable"
+```
+
+## Start Talos
+
+```bash
+docker run -d --name talos --network talos-preview \
+ -p 8080:8080 -p 4422:4422 \
+ -v "$PWD/config.yaml:/etc/talos/config.yaml:ro" \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ serve --config /etc/talos/config.yaml
+```
+
+This starts a single-tenant Talos commercial server with in-memory cache.
+
+## Wait for the server to become ready
+
+```bash
+# Wait for the health endpoint
+for i in $(seq 1 30); do
+ if curl -sf http://localhost:8080/health/alive > /dev/null 2>&1; then
+ echo "Server is ready"
+ break
+ fi
+ sleep 1
+done
+```
+
+The bring-up commands above are for local preview users. The executable API examples below are
+tested in CI against the commercial docs harness.
+
+
+
+
+Set the base URL for the local server:
+
+```bash
+export TALOS_URL="${TALOS_URL:-http://localhost:8080}"
+```
+
+## Issue an API key
+
+Create an issued key on the admin plane and save its secret for later steps. For the complete field
+reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys issue "preview-issued-key" \
+ --actor preview-user \
+ --scopes "read:profile,write:profile" \
+ --ttl 720h \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+export API_SECRET=$API_SECRET
+export KEY_ID=$KEY_ID
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "preview-issued-key",
+ "actor_id": "preview-user",
+ "scopes": ["read:profile", "write:profile"],
+ "ttl": "720h"
+ }')
+
+echo "$RESPONSE" | jq .
+
+API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
+
+export API_SECRET=$API_SECRET
+export KEY_ID=$KEY_ID
+```
+
+
+
+
+The response returns `issued_api_key` metadata plus `secret`, which is shown only once. Store the
+secret securely.
+
+## Verify the issued key
+
+Send the issued key secret to the unified verify endpoint. For the full response fields and error
+codes, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+
+
+
+
+
+
+```bash
+talos keys verify "$API_SECRET" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$API_SECRET\"}")
+
+echo "$VERIFY_RESPONSE" | jq .
+```
+
+
+
+
+An active result includes `is_active: true` plus the key's actor, scopes, issuer, and expiration.
+
+## Derive a JWT from the issued key
+
+Mint a short-lived JWT from the issued key with a custom claim. For the full request and response
+schema, see the [DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
+
+
+
+
+
+
+```bash
+RESPONSE=$(talos keys derive-token "$API_SECRET" \
+ --algorithm jwt \
+ --ttl 1h \
+ --claims '{"role":"preview-user","environment":"demo"}' \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
+export JWT_TOKEN=$JWT_TOKEN
+```
+
+
+
+
+```bash
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"credential\": \"$API_SECRET\",
+ \"algorithm\": \"TOKEN_ALGORITHM_JWT\",
+ \"ttl\": \"1h\",
+ \"custom_claims\": {\"role\": \"preview-user\", \"environment\": \"demo\"}
+ }")
+
+echo "$RESPONSE" | jq .
+
+JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
+export JWT_TOKEN=$JWT_TOKEN
+```
+
+
+
+
+The derived token inherits the parent key's permissions and returns as `token.token` with its own
+expiry metadata.
+
+## Import an existing API key
+
+Import a raw key string into Talos without rotating the credential. For the complete field
+reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+
+
+
+
+
+
+```bash
+IMPORTED_RAW_KEY=sk_preview_demo_001
+
+RESPONSE=$(talos keys imported import "preview-imported-key" \
+ --raw-key "$IMPORTED_RAW_KEY" \
+ --actor preview-import-user \
+ --scopes "payments:read,payments:write" \
+ --ttl 720h \
+ --format json \
+ -e "$TALOS_URL" 2>/dev/null)
+
+echo "$RESPONSE" | jq .
+
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
+
+export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY
+export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
+```
+
+
+
+
+```bash
+IMPORTED_RAW_KEY=sk_preview_demo_001
+
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"raw_key\": \"$IMPORTED_RAW_KEY\",
+ \"name\": \"preview-imported-key\",
+ \"actor_id\": \"preview-import-user\",
+ \"scopes\": [\"payments:read\", \"payments:write\"],
+ \"ttl\": \"720h\"
+ }")
+
+echo "$RESPONSE" | jq .
+
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
+
+export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY
+export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
+```
+
+
+
+
+Talos stores a cryptographic representation of the imported credential. The raw key is never
+returned after import.
+
+## Verify the imported key
+
+Imported keys use the same verify endpoint as issued keys. Talos detects the credential type
+automatically.
+
+
+
+
+
+
+```bash
+talos keys verify "$IMPORTED_RAW_KEY" -e "$TALOS_URL"
+```
+
+
+
+
+```bash
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$IMPORTED_RAW_KEY\"}")
+
+echo "$VERIFY_RESPONSE" | jq .
+```
+
+
+
+
+## Stop the preview
+
+```bash
+docker rm -f talos talos-postgres
+docker network rm talos-preview
+```
+
+## Next steps
+
+- [Issue and verify API keys](../integrate/issue-and-verify.md) — issued-key lifecycle in depth
+- [Import existing keys](../integrate/import-keys.md) — batch import and hashing behavior
+- [Derive tokens](../integrate/derive-tokens.md) — JWT vs macaroon and JWKS usage
+- [Key lifecycle](../integrate/key-lifecycle.md) — rotate, update, and revoke credentials
+- [Architecture](../concepts/architecture.md) — admin and data plane separation
+- [Cache configuration](../operate/cache/index.md) — switch from memory cache to Redis
+- [Docker quickstart (Commercial)](./docker-commercial.md) — full repo-based compose stack
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..d4b27218c3
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
@@ -0,0 +1,102 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "properties": {
+ "requests": {
+ "items": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "actor_id": {
+ "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ },
+ "title": "Keys to import",
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchImportAPIKeysRequest"
+ }
+ }
+ },
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..96d6267bfd
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
@@ -0,0 +1,185 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
+ "properties": {
+ "failure_count": { "format": "int32", "type": "integer" },
+ "results": {
+ "items": {
+ "description": "BatchImportResult contains the result for one key in a batch import request.",
+ "properties": {
+ "error_code": {
+ "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
+ "enum": [
+ "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
+ "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
+ "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
+ "BATCH_IMPORT_ERROR_INTERNAL"
+ ],
+ "type": "string",
+ "title": "v2BatchImportErrorCode"
+ },
+ "error_message": {
+ "title": "Human-readable failure reason",
+ "type": "string"
+ },
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ },
+ "index": {
+ "format": "int32",
+ "title": "Zero-based index in request.requests",
+ "type": "integer"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchImportResult"
+ },
+ "type": "array"
+ },
+ "success_count": { "format": "int32", "type": "integer" }
+ },
+ "type": "object",
+ "title": "v2BatchImportAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Batch import completed. Check per-item results for individual status."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
new file mode 100644
index 0000000000..c4846366de
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
@@ -0,0 +1,48 @@
+---
+id: admin-batch-import-api-keys
+title: "Batch Import API Keys"
+description: "Imports up to 1000 external API keys in one request. Returns per-item"
+sidebar_label: "Batch Import API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item succeeds, response is 200 OK.
+If all items fail, the endpoint returns a non-200 error.
+
+```http
+POST /v2/admin/importedApiKeys:batchImport
+{
+ "requests": [
+ {"raw_key": "sk_live_abc", "name": "Stripe key", "actor_id": "user_1"},
+ {"raw_key": "ghp_xyz", "name": "GitHub PAT", "actor_id": "user_2"}
+ ]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..aaea5e239f
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
@@ -0,0 +1,30 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "requests": {
+ "items": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyRequest"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchVerifyAPIKeysRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..fae100dcd0
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
@@ -0,0 +1,125 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "results": {
+ "items": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "issuer": {
+ "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
+ "type": "string"
+ },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyResponse"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2BatchVerifyAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
new file mode 100644
index 0000000000..dea1c3eaeb
--- /dev/null
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
@@ -0,0 +1,48 @@
+---
+id: admin-batch-verify-api-keys
+title: "Batch Verify API Keys"
+description: "Verifies multiple credentials in a single request. Efficiently verifies up"
+sidebar_label: "Batch Verify API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
+verified independently; partial failures are returned. Admin access only.
+
+```http
+POST /v2/admin/apiKeys:batchVerify
+{
+ "requests": [
+ {"credential": "sk_live_abc123..."},
+ {"credential": "eyJhbGciOiJFZERTQSI..."}
+ ]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..092cc31162
--- /dev/null
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
@@ -0,0 +1,11 @@
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
new file mode 100644
index 0000000000..cd80ba989c
--- /dev/null
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
@@ -0,0 +1,36 @@
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Imported key deleted successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
new file mode 100644
index 0000000000..df644d5bef
--- /dev/null
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
@@ -0,0 +1,42 @@
+---
+id: admin-delete-imported-api-key
+title: "Delete Imported API Key"
+description: "Permanently deletes an imported key (hard delete). The key is removed from"
+sidebar_label: "Delete Imported API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJzdVcluIzcQ/ZVCnSyDthwlM4c+RYgNRDMJ4njBHGwjppvVao7ZZA9ZrZmG0EA+Il+YLwmKLdnyggS+5sS1ql5tr9ZoKJXRtmyDxwJPKTbak2fXgyFHTAm0B9u0ITIZuKce9modzeZ1cggXNeVrmyBSE1ZkoIqhufZcExjN+k4nOoTLRHBGq3BP89PFR+qhChFSqHjUZIOHvUhlaBryhszk8Npf+9vb25q5vfbHJ7+cXJzAdDWbatNYP90imrf2I/Vpur6n/g9rhiyDCkNLUYvWhcEC5yJznBEvtoIZBSpsddQNMcWExdX6WTzOf56/+242nb17D7VONYQKxK2n8Tg7+f1ycXZyPEGFVqRazTUq9LohLHBEhgojfelsJIMFx44UprKmRmOxRu5b+Zk4Wr/EYbiRz6kNPlGS99nRkSxl8EyeZavb1tkyezj9nATr+qW+cPeZSsZhGNQzv+aQurKklKrOwdbUIQ4KZ0c/vMXUK7oXu8EZy8TsmHN9tmOo0p3jN7nVRkkr2zEoZTAkaxVioxkLtJ6/n6Haem8905LiaIy1dVnKMjV5o42xYke70121g3pm5sdR3cskqWdhVsiWnVy0MXC466q57/Hxm45R53NDKenlG3XGtjxnzV16NZ0eOk/fWiol1hRjiLtZFbV6KfWNosOWP0Uy5Nlql/BGAHEdpE/GbOWm4BoL/O9+yyVfBfHlKaTfYg8X2oUkxKChtsv6oKWYk+VLgpSBQPmABBrt9ZIa8gyJ4sqWdAgLhlp74yjlvpPy2RVxtqKyLx0VYFPqrF9K0SUFK4q26uXMNTWgGVz4Ck4z+bJXYCjalbymOkQ+cFZYi8M9+QR7Hz5dgPYGftWljiH4icrHKOQlMjpXcuYn4b756UJcTK2zDNZzAP4ath6kQr4dwP7+i8Dv78Pff/4FObzwQFepyG3z4BjsiWOkIAbWLGvmULWhoI0rtAGv4MOnj+eTjDeHYNNLGwjkqvMR18Z4IlcdbKBmzeP3zM07Ya6DM8KPj9X4mN356QIVriimMe+zwyOp8TYkbnTu3w0NjvQLD+wgcRsZ+Enh7NDB/2cabZqa6RtPW6etlxB10WVSy612hSuhrqxOeuqpQlRYbMbIjcI6JBaJ9VqcuYxuGOT6S0exx+LqRuFKR6vvJFMy0WySvcGi0i7Rv8R772wzoSbw5sH3qotb5vOS5pV2nZxQyUh8HIzDzaCwJm0oZrzj47wsqeUdsRejYdhlrjElOAz/AAf+FdE=
+sidebar_class_name: "delete api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Permanently deletes an imported key (hard delete). The key is removed from the database. Use RevokeAPIKey for soft deletion
+(recommended).
+
+```http
+DELETE /v2/admin/importedApiKeys/{key_id}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
new file mode 100644
index 0000000000..0fecc60986
--- /dev/null
+++ b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
@@ -0,0 +1,38 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "algorithm": {
+ "default": "TOKEN_ALGORITHM_UNSPECIFIED",
+ "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
+ "enum": [
+ "TOKEN_ALGORITHM_UNSPECIFIED",
+ "TOKEN_ALGORITHM_JWT",
+ "TOKEN_ALGORITHM_MACAROON"
+ ],
+ "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
+ "type": "string"
+ },
+ "credential": {
+ "title": "The API key secret (issued or imported) to derive a token from",
+ "type": "string"
+ },
+ "custom_claims": { "type": "object" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ }
+ },
+ "title": "Token derivation messages",
+ "type": "object"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
new file mode 100644
index 0000000000..7b33c4812d
--- /dev/null
+++ b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
@@ -0,0 +1,51 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "token": {
+ "properties": {
+ "claims": { "type": "object" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "token": { "type": "string" }
+ },
+ "title": "Token represents a short-lived derived token (JWT or Macaroon)",
+ "type": "object"
+ }
+ },
+ "type": "object",
+ "title": "v2DeriveTokenResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-derive-token.api.mdx b/docs/talos/reference/api/admin-derive-token.api.mdx
new file mode 100644
index 0000000000..5ab852e102
--- /dev/null
+++ b/docs/talos/reference/api/admin-derive-token.api.mdx
@@ -0,0 +1,46 @@
+---
+id: admin-derive-token
+title: "Derive Token"
+description: "Mints a short-lived JWT or Macaroon token from an API key. Works with both"
+sidebar_label: "Derive Token"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys. The derived token inherits
+the permissions of the parent API key.
+
+```http
+POST /v2/admin/apiKeys:derive
+{
+ "credential": "eyJhbGciOiJFZERTQSI...",
+ "ttl": "1h"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..092cc31162
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
@@ -0,0 +1,11 @@
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
new file mode 100644
index 0000000000..b6035db77e
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
@@ -0,0 +1,125 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
new file mode 100644
index 0000000000..facf37bc9c
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
@@ -0,0 +1,41 @@
+---
+id: admin-get-imported-api-key
+title: "Get Imported API Key"
+description: "Retrieves details about a specific imported key. Returns metadata about"
+sidebar_label: "Get Imported API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Retrieves details about a specific imported key. Returns metadata about the imported key. The original raw key is never returned.
+
+```http
+GET /v2/admin/importedApiKeys/{key_id}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..b19b7ceb16
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
@@ -0,0 +1,10 @@
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..f922dc595f
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
@@ -0,0 +1,122 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
new file mode 100644
index 0000000000..ba08065ba6
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
@@ -0,0 +1,42 @@
+---
+id: admin-get-issued-api-key
+title: "Get Issued API Key"
+description: "Retrieves details about a specific issued API key including its status,"
+sidebar_label: "Get Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Retrieves details about a specific issued API key including its status, scopes, expiration, and usage statistics. The secret is
+never returned.
+
+```http
+GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
new file mode 100644
index 0000000000..07c363956d
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
@@ -0,0 +1,42 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "jwks": { "title": "JSON Web Key Set", "type": "object" }
+ },
+ "type": "object",
+ "title": "v2GetJWKSResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-jwks.api.mdx b/docs/talos/reference/api/admin-get-jwks.api.mdx
new file mode 100644
index 0000000000..c26fbd7e10
--- /dev/null
+++ b/docs/talos/reference/api/admin-get-jwks.api.mdx
@@ -0,0 +1,38 @@
+---
+id: admin-get-jwks
+title: "Get JWKS"
+description: "Returns the JSON Web Key Set for token verification. Provides the public"
+sidebar_label: "Get JWKS"
+hide_title: true
+hide_table_of_contents: true
+api: eJztVc1u4zYQfpUBT0mg2Knb7gI61VjsBs6i3SD2Igc7QGhyZDGmSJUcKSsYBvoQfcI+STGUEjvpYotFrz3xRzPffDOc+bQTGqMKpibjncjFDVITXAQqEa7mn36DW1zDR+xgjgSFD0B+iw5aDKYwSrLXCK6Db43G3qtu1taoldtiF8EhatRAvvfo4Op20UNEMDE2qGHdAZUmQsTQGoUjjhZBBgTrpUa9ckXwFSjvCrNpQgoJJ4WxmI/HGZREdUw7H2AtI775KR+P4fPNLJ6O4IO31j8mYit3dftxDpGk0zJoOLn58A7e/vzD29PRyq3c/f09Q63c5fsFjNvJWOrKuLHGYFrUzGn88LiNo4foe2uRCV9jz2emRS6m7HCJxGFEJgLG2ruIUeQ7Mbm44EV5R+iIt7Ku7VDAMWPyXVQlVpJ3dWBsMr03B+aVDFkUuXj9MCIT1NX8xa8fUJHY71/fZM/O7WTgeDMQFHs2f9kGU4iNUhhj0Vh4ymQkkl0hG0v/IRvlNfJa+FBJErkwjn6cHHIwjnCDoQ9G0tjkZQirtJFaG44j7fUx7D57FeaXHm73BBspGLf5Zmnq4Mmvm2LqOnEwkyHIdK4wRrn5TsxQqzlJauJXy+ygcfilRkWoAUPw4bjaDCs3UeRLwRhGvQuo0ZGRNoo7JkSl59bbpB6oJZUiF//SvCITxhWes3hJ5lPoYCGt58kECaXZlOc1hvRMTiFPDhkF6pkDVNLJDVbo6DC9M4JSOm0HNSgaa49drClQdcpinubfuA2wUGSDPvCZSqxAElj/CFYSOtVlkFLhr7H0gc4t5/UkJCcsKtJp+FUqGbx3p1k6Bmz9ln1kauU05osSYXo94xRjbQ2BceSBHv1TBjFns3M4O/tHyc/O4K8//oRUW3ie/ZhzBofE4CQJWwbBkyRemQZmYKraBxpSwYF8BjyKp4nvsagOFNAW857XEDyiLc4Hqgm5N0/SfFTm0luNIR714eF1p9czkYkWQ+zffTK64O6ufaRKpsl1smKXSyQYxOxFpxxN/v//i+/5XwwaQfiFxrWVxnHdm2CTRqbhXYqWlTBhpbI/o4lMHEb4LhOlj8T2ux0n8TnY/Z6vf28wdCJf3mWilcHINT/+8m6fiRKlxiDy5U5ssWPxUQpr1o1W2iYJ3WsR3x9rzOX7hdjv/wayxNug
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
+Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
+
+```http
+GET /v2/admin/derivedKeys/jwks.json
+```
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
new file mode 100644
index 0000000000..0d8212aaf6
--- /dev/null
+++ b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
@@ -0,0 +1,91 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "actor_id": {
+ "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ }
+ }
+ },
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
new file mode 100644
index 0000000000..171404d5ed
--- /dev/null
+++ b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
@@ -0,0 +1,135 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key imported successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-import-api-key.api.mdx b/docs/talos/reference/api/admin-import-api-key.api.mdx
new file mode 100644
index 0000000000..4bf6b63c79
--- /dev/null
+++ b/docs/talos/reference/api/admin-import-api-key.api.mdx
@@ -0,0 +1,47 @@
+---
+id: admin-import-api-key
+title: "Import API Key"
+description: "Imports an external API key into the system. Allows importing keys from"
+sidebar_label: "Import API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is
+hashed and stored securely (HMAC). Imported keys support token derivation (JWT/Macaroon) like issued keys.
+
+```http
+POST /v2/admin/importedApiKeys
+{
+ "raw_key": "sk_live_abc123xyz",
+ "name": "Imported Stripe Key",
+ "actor_id": "user_123"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
new file mode 100644
index 0000000000..11096ba113
--- /dev/null
+++ b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
@@ -0,0 +1,72 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssueAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
new file mode 100644
index 0000000000..2cfb37410c
--- /dev/null
+++ b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
@@ -0,0 +1,136 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "Only returned on creation",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2IssueAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key issued successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-issue-api-key.api.mdx b/docs/talos/reference/api/admin-issue-api-key.api.mdx
new file mode 100644
index 0000000000..0d2b092b6e
--- /dev/null
+++ b/docs/talos/reference/api/admin-issue-api-key.api.mdx
@@ -0,0 +1,48 @@
+---
+id: admin-issue-api-key
+title: "Issue API Key"
+description: "Creates a new API key for a given actor. The secret is returned only once"
+sidebar_label: "Issue API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJztGtuO27j1Vw745Alkjz2TzAYuCtRxnKxymTFsJ+kiCry0dGxxI5EKSdkjDKboR/QL+yXFIeW7M9tsHwq0kwECkzw6PPebdMcSNLEWhRVKsi7ra+QWDXCQuILeMISvWMFcaeCwEEuUwGOrdAsmKYLBWKMFYUCjLbXEBJTMKlAyxkgKCTZF0GgKJQ0ClwnEXEplYUbbVgtcYgIZt6hb8BYrQ+d0aGJVYAIrYdNImgJjMRcxFKhzYYxQ0jhkKV8iKEc5zwBvC6E5LVqRjOSvv/6aWltEcngznsD58uKcJ7mQ58KYEpNeIei+SN5FEiBikucYsS5ErNAqKWNC0zSolyLGiAUeyHE+FYkHLA3qaeficnPsiDZ0+DliGnkSsQAittLCYsS+1FDWZv755z9dtdOIRfLeEcsCpgr0DIQJ67IekRsStb1h+BYrFjCN30o09oVKKta9Y7GSFqWln7woMhG7h89/M6TJO2biFHNOvwpNqK1A42BrNui3rQpkXWasFnLB7gMmiqlGWsbeIO4O7CMcjrbHkOBcSDQQDpszbjABHsdoDBBlWmXGG45c21Erkp9SMqEsUytMprFItCHzkUo2MS9sFXgDqhk1MNcqh3BoIOc2ToVcALeQITcWlMRI9sOXI9BcLhC4Rm8h1mLSggGhO7gpRy7pMgiHsMMlNHiWuVtq8LNWJPdBDJCEK7AKtFJ24xhkhiIvlLaYuI0larJVpwnHy58imaAWZOhWfUVpoPHm0+Q85zHXSskzR7ex3GJGkiOE5CGmnP2GsaULwyHEKcZfTYsFh6rcZe9YWUdy5pAJEt0ctoIzYFNuHRk1PF1aGgSbClOrbVwWxKSBmbIphMPlU2hga9EiA++0W+7v/HnEzhwD4XB5tT2/aLc73WT2vNs9v7yImBPuHGp1byS/c31Dql3ZnxHfwmJuTlpsvcG15hW7324oJ0AWMCtsRhvLiz3jpWdztDzhlu8grh+7D1xMOHmj5hanmciFnRYqE3F1LPkRt/iOIIYOAPzpzAkbgRCAQwAewbGfRDKUcDMeQ64SDLwqalhhQMi50jmvIx+JnEzbWcsMyftMmWMCsyqSZWGsRp7Dgltc8cpAYyCXqgqgn6kymWdcYwBo49aZowIJdYw5SttyRMQqz1HHgmc1LROeKbOGMzvMGCgNuaiQzRxzpStQGkaYCAMzHn9FmZggks6CCrVC7Sh0AnndH/Wg8RolahFDH7MMSILQyxZKC5vmZ04kfZUXmSBGKTNAovncNgXaeZNCPS9Ek4hxtDRT5Alq0+y0j93mW6m8zveV5rZJvESSLPMZanKVTTBa22eBGlZCJmpFqL0mWJcJaa+esuDYXkopXJBeGyKtDyzCX+0O6PFWJF/inJeZpUyxJoCSxY1NUcOSZyKh/0s0jpxwMHkFlCgJvs4LzVllKR8FfisutabdLbZTtHq+jmXj99fCsSLHWgTOaDYstJySciVr4rpw1TbQ6EAuZGnxLIDLq7bfSVWpzwJ4fvW03kh45Vz9gKYHPfrAz5x3ev7WCa4G7WeCmK8TU4YJiATzQlmUceUid6MXDpudZ8/OTonF53ZC+O8GooAy/bEcrc3AoPVidCVLBZwCc1L63O9TnlSrViR7cYwFZRZvY6ZLJUQTBrcWZYIJ6bpTRQwal1fPkjMXi3Pl1u16uaLVT/UiocXF0/TMoxlbLhOuE3itCNPF09TbymU79z+u2rX1dFK35x8jJ1SlrG+/ogs99s5FjeBidZkQdK8otLoVPk6ZLnQq+DNcXj0jTZsAOrmiddstfVIopUEbONkUWrkEmHg/gMnkncvBAk0L3vNbkZc5mePfOm2okGsDjcvOM7KudtucsqOALYURM5EJWwdsh5h12dvBL9OP4Th8Eb4LJ79MP1yPh4N++CocvGTBgfreYvVxgwUSYayQi1KYlPywnGUihkbsTc3wOZ6RZdVVTF0sN6iqRN2k2sAftyI59I86YMq8HBIxnyP5K0XzuViUms8ykgrOxa3zuaUwJc9qGuK67n1BwZUYN2BSyqkkSsPzuqQ+35bQYCpjMYd//v0fsBWMKxJmqrRkm8qUVJvwOVqfkqAJ35dVFyaud0jInseD/mgwYQFDWeas+/lhGR8cbh4+2B9+ePEu7LMvh6rdDQh7Cvq9cmBbXI980GD393UEERoT1rW6xIDdNpUWCyF5NuSa59euLmAzqsIdtO9vXFC4aLf/g8rc9yZTXojpVzxRVYS+d3EUg8ZCo0FJiWlTOYBHAY0F5VLSxhnlWJeyW5EcUe3qrIxsQxX8W4mw7NTxZV2gGqsoN9f9G9VHVNy7nHRcyL7fK2Tj2gSWgoOHnhCsK1H2C92Gq3LdTWcnCtuHehR/yZSSEJ1vEnDCLTbd7gnnd7H2Rx967IYeu6H/n27oK1bfc7mMGzstDSY/6ECPDdZjg/XYYP2vNVhL5UP6dI+FQ45Ow1FhvxQJUjZDbJJyXYLEW1uPmbfPtSJ5QwnQoIUVpcodlBq5UZLkNRyFH8N3g9eD6adw8vPLUe/TdSuSb8Y3187d45TiehfmArMEVtyl4Ry1S6wH6KZERgteOdDaQDuXkRQGSukRJWCUU4dfEgErobEZq7zgVlCRTmzMhOS6ImatApSxSoRcnOxKjojYb05Gg483/d4kvLmejga98c31g/3JaINs5OWzkbaxuoxtSTFheyP4GyneGSqPXLwYverDs4vn7VYkPxhfB7qQ4ubnLhYazObNHSzzTK3MukM4JviEgrrgxtuuC+q6FL/2fSEP0e90Eb8njONzaiH6N++Ho5v34XhwEqT36lX4LvRb/Z9716+/g2r8YTgYjQcvv3N8gsuHW5VDXf3ROQOVS6U5bmnHk97kw/hAQrv92EmAnYNefxJ+HOzvEd9vDwEHfx2Go8HL3+3Mxp5SithF8uMl/GP//ti/H/XvdTvsHMFpaLcQuPHt0+bdpO9PfUz5kSy4Nynw7b4fFexbVw9M6Vq+eZlt3nu2iLSLdudH5gKncO83+NuLssrdsHGHPzx9iFWy74xC2suLraSEtLhA7S+zXGT7cYonifD18nAX7f1hbfgXj+4osD2gAJdFZ+W8J6tTATBHY/jiB3HqIl6HoxPCllBKvC0wJn9ArZXe1Seh5QtDfkE4RNzXmKC0gmeGzDtHmyp6h1soQ3cW3Kasy77zEpoFjFQz2r7cHdzyvMhwfxCy9ZbjqcRB5/t5DftlvwXb9FxbXCdbrbp830L5Anu7Xhexe2XMduy+BVznsy1F9Vx8C7Ib1R8KMzSOkXN1XGfe6HrA5Xv6VCzSZoHambGM/ThBxOT6tY4g55IvXAcG9Tv+FoQWUi6TrO4XyLF2H8nEHOMqzrDrPJC6MIr2gR9xVLS2KeZuIKNW7psGGVcBuGkHnZpUadvMDkcfrp7azNACt6TS56ub7jgfd6GbPregECAMmCITFoS0CuxKrTmglwORbMKTJ0cm+eSJyxK+ftt8ZGC6Lp5sGIOGs8oAtKL5S+DJwKCe6NSsYE18AG8+vR37AcfulKcmAbP52NNVX+5quprU3QKUMuGOmFOVUVO546db7faGIZkLauP1ftFqk1GQj+XcuUFt3C5aO2n5zyYOupRNeHz82OW/+LFLHZep4TovMi5c+Vtq98rMx8vPbEnZx3FCUW8vZn4JWErBtfuZ3d3RtPWDzu7vaftbibpi3c9fArbkWlDZRav7gPmJBet+vmNuvM76dR8/IVoIPCtdYjlMmvfB+gn/Ru5B2N34T+pggX9V0L1jucuwTPOVi7wUQN1nP84dCcDt3bGMy0XpMhrzOOnfvwBaMQVE
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Creates a new API key for a given actor. The secret is returned only once in the response and cannot be retrieved later. Keys can
+be scoped with specific permissions and have optional expiration.
+
+```http
+POST /v2/admin/issuedApiKeys
+{
+ "name": "production-service",
+ "actor_id": "user_123",
+ "scopes": ["read", "write"],
+ "ttl": "8760h"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
new file mode 100644
index 0000000000..76d4d28b3c
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
@@ -0,0 +1,22 @@
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination (OPTIONAL)",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..a28a55dec5
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
@@ -0,0 +1,145 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_keys": {
+ "items": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ },
+ "title": "List of imported keys",
+ "type": "array"
+ },
+ "next_page_token": {
+ "title": "Token for fetching the next page (empty if no more results)",
+ "type": "string"
+ }
+ },
+ "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
+ "type": "object"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
new file mode 100644
index 0000000000..de3457870e
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
@@ -0,0 +1,42 @@
+---
+id: admin-list-imported-api-keys
+title: "List Imported API Keys"
+description: "Lists all imported keys with filtering. Returns imported keys only (not"
+sidebar_label: "List Imported API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports pagination and AIP-160 filter
+expressions.
+
+```http
+GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
new file mode 100644
index 0000000000..4a5e5fb847
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
@@ -0,0 +1,22 @@
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
new file mode 100644
index 0000000000..e9fcb6db7c
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
@@ -0,0 +1 @@
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
new file mode 100644
index 0000000000..e0da39abf9
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
@@ -0,0 +1,138 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_keys": {
+ "items": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "type": "array"
+ },
+ "next_page_token": { "type": "string" }
+ },
+ "type": "object",
+ "title": "v2ListIssuedAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
new file mode 100644
index 0000000000..63fa1c0539
--- /dev/null
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
@@ -0,0 +1,42 @@
+---
+id: admin-list-issued-api-keys
+title: "List Issued API Keys"
+description: "Lists issued API keys with optional filtering. Supports cursor-based"
+sidebar_label: "List Issued API Keys"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "get api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter expressions. Returns only
+issued (generated) API keys; use ListImportedAPIKeys for imported keys.
+
+```http
+GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..b19b7ceb16
--- /dev/null
+++ b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
@@ -0,0 +1,10 @@
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
new file mode 100644
index 0000000000..fe11762f69
--- /dev/null
+++ b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
@@ -0,0 +1,34 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "description": {
+ "description": "Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.",
+ "type": "string"
+ },
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminRevokeAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
new file mode 100644
index 0000000000..d3cec6dad6
--- /dev/null
+++ b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
@@ -0,0 +1,36 @@
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key revoked successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
new file mode 100644
index 0000000000..9ebbf602ee
--- /dev/null
+++ b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
@@ -0,0 +1,45 @@
+---
+id: admin-revoke-api-key
+title: "Revoke API Key"
+description: "Immediately revokes an API key (issued or imported). Once revoked, the key"
+sidebar_label: "Revoke API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJydVttu20YQ/ZXBPiUGJbtqC6R8quLICePEkiUlzoWBs+KOxI2Xu+zuUDZhEOhH9Av7JcUuGVmRFATpA0EuOZwzlzOXeybQZVaWJI1mMUuKAoXkhKoGi2tzgw64huEkgRus4ZF0rkIBxoIsSmMJxeM+jHWGnbSIgHL0sqnOuAZtQBm9QgsLhMqhgKWxwCvKUZPMuIftwzyXDkyJNpxBOpDW4hqtkwuF/VRPW+VerwNuPRpxqTfqhCQoK1sah66f6lR//vw5JypTPRnP5nC8HhxzUUh9zEt5jrU7PvnlxeWHd3+8fX95/vLpk3eXHy7b691l3DqS6vtUA6TMIndGpyyGlE1Hb8enw3kyvriejoaz8cX1+ej99en49WQ6fp3MRilLdRPAWcQ2/iSCxWzo4Vs3hpPkHGsWsZJbXiChdSz+eM+kT0DJKWcR07xAFrMbrK+lYBGz+FclLQoWk60wYi7LseAsvmdUl17SkZV6xZrmUyuMjp4aUXuJzGhCTf6Rl6Xqon78xfmM32+pKq23mSQ6f/qGGDtHNg4PXMHSIvYI7wjwrlRcdxkda1UDV8rcooDbHDW0cfS5nUyTt8mr0fPR9VUyf/FsOry66LNo15Goi3yLveSVIhYfyMCbi9lkdJqcJaNnLNqx0se79XbaopfWrKVAB45slVFlUQTitkKdjQ6kdqWPNixqmJ6dwu+DJyf9VL/x/JUaFoZyCHwCrgU4VMvelpalMrctC6EH+wYfcD+GQI+e0aqOQRvahE7qXfUsYqirgsUffxiMH9H1oMjw7Cx5lbSvTl8ML55/R9XszWQ0nY2efefzAS/Zp90kR4wkKf9iPdjNFWuajbhZfMGMtsRnxElmpxaFbyNcub3yCuRvmma/dO56xsqV1FxNfP1dtJW2CPJe2pVGu7YEBicnP1VA35ob0L8l5BBclWXo3LJS8BWq73EHJ7/9DNQh3V2P7hrxFpKqA8Smiv53S8iMQH9fGltwX45S06+Dh9qVmnCFtgUjLlX4SxIW4YELIdu2MdlW20Q7MH+26vZ72/cJUVpDZlEthzpksRPj1vJwLtA5vvpJnbbMPM8qdzCTGiqNdyVmhALQWmO3E+rV8pXv6/tc9XVQIOXGz4XSOAqjgHIWs/1Bdd+OgKYbSyxiPknThw4/uuNFqXC/RW9q7Gsf/UG/aCIm9dIc6PW2hjlXxvnmzSGXq7xXog0k8JPfBQch23gIBdd8hQVqAod2LTPsQ0KQcy0UurAheFpu/6LkErM6UxiD3zGkXoVhH8EarVzW/kw5FsAJlLkFxQl1Vkcg0Mq1/+pyY6mn5BoFkLlB7eDRy6t56NCvecatMfpxFI4hlP4fHioktOp5jmHLkQ5cqSSB1GSAbs1XD1zsxXpwdLSX0KMj+Pfvf7qJsBn7Lg7luHGsW54isIY4+XvIaNRtUp0r2Bkfwcur89njYG8IQVejnQmolrPWrg48TInO1O2R5vejrTDnRgm/bzyw/CG7w0nCIha2rpD3Qf+ENc1/EaGFAA==
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for authentication. This
+operation is irreversible. Revoked keys are retained for audit purposes.
+
+```http
+POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
+{
+ "reason": "REVOCATION_REASON_KEY_COMPROMISE"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..f832c1b781
--- /dev/null
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
@@ -0,0 +1,11 @@
+{
+ "parameters": [
+ {
+ "description": "key_id is the ID of the existing API key to rotate",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..a6617b6abd
--- /dev/null
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
@@ -0,0 +1,77 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": {
+ "title": "metadata for the new API key (inherits from old key if not provided)",
+ "type": "object"
+ },
+ "name": {
+ "title": "name for the new API key (inherits from old key if not provided)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "scopes for the new API key (inherits from old key if not provided)",
+ "type": "array"
+ },
+ "update_mask": {
+ "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminRotateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..8c6dc535d3
--- /dev/null
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
@@ -0,0 +1,223 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "old_issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ },
+ "secret": {
+ "title": "secret is the new API key secret (only returned once, never retrievable again)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RotateIssuedAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key rotated successfully. New key issued, old key revoked."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
new file mode 100644
index 0000000000..f7679ff402
--- /dev/null
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-rotate-issued-api-key
+title: "Rotate Issued API Key"
+description: "Generates a new secret for an issued API key. Creates a new API key with a"
+sidebar_label: "Rotate Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret, and immediately revokes the old
+key. This is the recommended way to update scopes, metadata, or rotate credentials.
+
+For zero-downtime rotation, use this workflow instead:
+
+1. IssueAPIKey with new credentials
+2. Deploy new secret to all services
+3. Verify new secret works everywhere
+4. RevokeAPIKey to remove the old key
+
+```http
+POST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
+{
+ "scopes": ["read"]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..5881cc93c2
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
@@ -0,0 +1,11 @@
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED, path param)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
new file mode 100644
index 0000000000..432ca719c3
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
@@ -0,0 +1,56 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "update_mask": {
+ "title": "AIP-134 partial update mask",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminUpdateImportedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
new file mode 100644
index 0000000000..b6035db77e
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
@@ -0,0 +1,125 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.api.mdx b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
new file mode 100644
index 0000000000..87ba190cee
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
@@ -0,0 +1,45 @@
+---
+id: admin-update-imported-api-key
+title: "Update Imported API Key"
+description: "Updates metadata, scopes, or rate limits of an imported key. Supports"
+sidebar_label: "Update Imported API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "patch api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Updates metadata, scopes, or rate limits of an imported key. Supports partial updates via update_mask (AIP-134).
+
+```http
+PATCH /v2/admin/importedApiKeys/{key_id}
+{
+ "name": "New name",
+ "update_mask": "name"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
new file mode 100644
index 0000000000..b19b7ceb16
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
@@ -0,0 +1,10 @@
+{
+ "parameters": [
+ {
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
new file mode 100644
index 0000000000..00ba7a70c8
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
@@ -0,0 +1,53 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "update_mask": { "type": "string" }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminUpdateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
new file mode 100644
index 0000000000..f922dc595f
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
@@ -0,0 +1,122 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2IPRestriction"
+ },
+ "key_id": { "type": "string" },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
new file mode 100644
index 0000000000..c500f6645d
--- /dev/null
+++ b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
@@ -0,0 +1,46 @@
+---
+id: admin-update-issued-api-key
+title: "Update Issued API Key"
+description: "Updates metadata, scopes, or rate limits of an issued key without rotating"
+sidebar_label: "Update Issued API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "patch api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedAPIKey to change the
+secret.
+
+```http
+PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+{
+ "scopes": ["read"],
+ "update_mask": "scopes"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
new file mode 100644
index 0000000000..b4df248475
--- /dev/null
+++ b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
@@ -0,0 +1,21 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
new file mode 100644
index 0000000000..15e5a9ea5b
--- /dev/null
+++ b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
@@ -0,0 +1,113 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "issuer": {
+ "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
+ "type": "string"
+ },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2VerifyAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-verify-api-key.api.mdx b/docs/talos/reference/api/admin-verify-api-key.api.mdx
new file mode 100644
index 0000000000..7cdaf0e35a
--- /dev/null
+++ b/docs/talos/reference/api/admin-verify-api-key.api.mdx
@@ -0,0 +1,52 @@
+---
+id: admin-verify-api-key
+title: "Verify API Key"
+description: "Verifies a single API key or derived token. Validates the credential's"
+sidebar_label: "Verify API Key"
+hide_title: true
+hide_table_of_contents: true
+api: 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
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with
+any credential type (issued keys, imported keys, JWT, macaroon). The verification result includes decoded claims and metadata —
+admin access only.
+
+Cache Control (HTTP Headers):
+
+- Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
+- Cache-Control: no-store - Bypasses cache read AND write (never cached)
+- Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
+
+```http
+POST /v2/admin/apiKeys:verify
+{
+ "credential": "sk_live_abc123..."
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
index c7988c3cc4..75fcaa9cef 100644
--- a/docs/talos/reference/api/ory-talos-api.info.mdx
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -2,8 +2,8 @@
id: ory-talos-api
title: "Ory Talos API"
description:
- "Ory Talos is a high-performance API key management service. It handles the full credential lifecycle: issuing keys, verifying
- them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
+ "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
+ verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
sidebar_label: "Ory Talos API"
hide_title: true
custom_edit_url: null
@@ -19,19 +19,18 @@ import Export from "@theme/ApiExplorer/Export"
-Ory Talos is a high-performance API key management service. It handles the full credential lifecycle: issuing keys, verifying them
-at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
+Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
+verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
-The API is split into two planes:
+The API is split into two services:
-- **Admin Plane** — key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
-- **Data Plane** — high-performance verification (single, batch, self-revoke)
+- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification
+- **SelfService** — self-service revocation for credential holders
### Quick Links
-- [**Admin Plane**](./admin-plane-service-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens,
- JWKS)
-- [**Data Plane**](./data-plane-service-verify-api-key) — High-performance verification (single, batch, self-revoke)
+- [**Admin Plane**](./admin-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
+- [**Data Plane**](./admin-verify-api-key) — High-performance verification (single, batch, self-revoke)
```mdx-code-block
import DocCardList from '@theme/DocCardList';
diff --git a/docs/talos/reference/api/revoke-api-key.RequestSchema.json b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
new file mode 100644
index 0000000000..5f67130aa1
--- /dev/null
+++ b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
@@ -0,0 +1,36 @@
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "properties": {
+ "credential": {
+ "title": "Full API key secret or imported key (REQUIRED)",
+ "type": "string"
+ },
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2RevocationReason"
+ }
+ },
+ "type": "object",
+ "title": "v2SelfRevokeAPIKeyRequest"
+ }
+ }
+ },
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/revoke-api-key.StatusCodes.json b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
new file mode 100644
index 0000000000..506ca96823
--- /dev/null
+++ b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
@@ -0,0 +1,40 @@
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
+ "type": "object",
+ "title": "v2SelfRevokeAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/revoke-api-key.api.mdx b/docs/talos/reference/api/revoke-api-key.api.mdx
new file mode 100644
index 0000000000..69dee11285
--- /dev/null
+++ b/docs/talos/reference/api/revoke-api-key.api.mdx
@@ -0,0 +1,48 @@
+---
+id: revoke-api-key
+title: "Revoke API Key"
+description: "Allows an API key holder to revoke their own key. The caller must provide"
+sidebar_label: "Revoke API Key"
+hide_title: true
+hide_table_of_contents: true
+api: eJztV9tu4zYQ/ZXBPCWB7KRZFCj0VDdxdrXZTVw72aCIgiwtjS1uKFIlKSeCYaAf0S/slxQk5Uu83g0C9KEo6hdL5HA4lzNnRnPMyWSaV5YriTH2hFCPBpiE3iCBB2qgUCInDVaBppl6ILAFcQ3qUbrtLlwVBBkTgjSUtbFQaTXjOaXSFgSTWoiVJkOZJgvMOBk1ATWBShlDxnAluzCqq0ppa4AbU1O+PGZSyWQOvHSblPulLry/uQK3XLKMaaUkWPVA0kDGpFQWxgSGxKQTTM5hzxbUpJJpAmOZJUHG7HdTmUpn/mCYfEo+9N/272+Sq3enw97NBWhiRkngBpw+5sJCOUyUXivOmAtaKvdYXnLZUVI0Qefnz58La6tUDi5HV3A4Oz5kFT+nxsTu7NDblMp5KgFSzDTlJC1nIsUYUjQP94LP6J6Nsx+O33S73RSjIBlMClLD/qfLk95VcnlxP+z3RpcX9+f93+5PLj8Ohpcfk1E/xVQuvCUYoapIe1uTHGMM9/cGyTk1GKGm32sy9heVNxjPMVPSkrTukVWV4MHJwy/GwWOOJiuoZO7pOW5GK8eC4mHQGgL3Cjylcty0EOJyCisMvYwfjLDSzlPLyXhPVoF1b5ZbQRjj2Q5EKv0MXrA37P96nQz7p/sYoW0qd85YzeUUF1GbhhCCCauFdTH9Kh3XF6NB/yQ5S/qnGG0Fa7gCzzCgrK0ZA8bqOrO1phzWCGuxaIBLU3G3N25geHYCPx7/dNRN5bWhHLiEsbIFeCz60tjCKUxcJjw+oQNfG7yjCGLorZAdP6sDLrfVY4Qk6xLj2xeD8RJ2d4r0zs6SD0lYOnnXu3j7DVWj60F/OOqffmN7h5d4t53kaIWW2fF2rnCxWImr8RfK7DPxb9QBLtyxf2HJuOp3kMLY6poifOoozadcMjFgmpUXrHR+jR05eOibSkkT6uv46OgfJYyg2jGuJltrSTkoCabOMjJmUottxHko98vKNhty+LrkhDt3Zae3efPS7y56ubbqX+H7FjOpnNz/ROmSOfrg0r45XpvOpaUp6XCZZVz4U9xS6R9YnnN3DxODTbWLbQL8Oaibb1PYdwBcaWXVuJ70pM93K8a0Zv69JGPY9JU6dZWNLLO12RlmCbWkp4oyR76ktdKb0XZq2dQ4VnHJG5Ge8YxcxZZkC+XaWaWMu61itsAYdzdbjNDlZLhudf0nVlaCtvvEmgGWLP8Cmy0i5HKivsb3pW7gignlxhlgUPBp0alI+5TLLIwhPIP15VAyyaZUkrRggp9dSCwUTOaCzLquN44IPqGsyQTFfmhy5e/GowhmpPmkaemgBGZBqEcQzJLMmghy0nzmdk2htO24eSNfTlB7y9HqYzta7Uf+1VOPO8N8WayGJ0dS3ICpBLfApVVgH9XSAxM7sQ4cHIy8vycr283BAfz1x59tv1pNKCb2vLVyDPb8NBiBVm5ui1oGjNqG3bpCrfERvL85H+17e30I+HJG8yasEdRe7hmlNXWz4boxbyPMgX/NBqbX2e0NEoxwRtqEvB93jxwoHCpL5llABg4NSPThCoPXM7xscMn/M/h/cQZv2dHSkz2sBOPSoaTWfjYN3HWLM9cDdrDXXYSFY7n4FufzMTN0rcVi4ZZ/r0k3GN/eRThjmrOxQ+ft3SLCglhOGuPbOT5QgzGeBHx1rpwhTlzUntu3+9YiWp7oZRlV9ruym0TsAo1RmBXiOZa+yaFmj45N2SPG6D9FfJU7Ab82R8HktPZNBYNO9/sbqPUS1A==
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Allows an API key holder to revoke their own key. The caller must provide the full API key secret as proof of possession. Supports
+issued API keys and imported keys. JWT and macaroon tokens cannot be self-revoked (they are stateless).
+
+The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
+
+```http
+POST /v2/apiKeys:selfRevoke
+{
+ "credential": "sk_live_abc123...",
+ "reason": "REVOCATION_REASON_KEY_COMPROMISE"
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
index f1e07edea7..e688743952 100644
--- a/docs/talos/reference/api/sidebar.ts
+++ b/docs/talos/reference/api/sidebar.ts
@@ -4,87 +4,105 @@ const sidebar: SidebarsConfig = {
apisidebar: [
{
type: "doc",
- id: "talos/reference/api/ory-talos-api",
+ id: "reference/api/ory-talos-api",
},
{
type: "category",
- label: "AdminPlaneService",
+ label: "StaticCredentials",
items: [
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-get-jwks",
- label: "Get JWKS",
- className: "api-method get",
+ id: "reference/api/admin-revoke-api-key",
+ label: "Revoke API Key",
+ className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-revoke-api-key",
- label: "Revoke API Key",
+ id: "reference/api/admin-batch-verify-api-keys",
+ label: "Batch Verify API Keys",
className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-derive-token",
+ id: "reference/api/admin-derive-token",
label: "Derive Token",
className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-list-imported-api-keys",
+ id: "reference/api/admin-verify-api-key",
+ label: "Verify API Key",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "reference/api/admin-get-jwks",
+ label: "Get JWKS",
+ className: "api-method get",
+ },
+ {
+ type: "doc",
+ id: "reference/api/admin-list-imported-api-keys",
label: "List Imported API Keys",
className: "api-method get",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-import-api-key",
+ id: "reference/api/admin-import-api-key",
label: "Import API Key",
className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-delete-imported-api-key",
+ id: "reference/api/admin-delete-imported-api-key",
label: "Delete Imported API Key",
className: "api-method delete",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-get-imported-api-key",
+ id: "reference/api/admin-get-imported-api-key",
label: "Get Imported API Key",
className: "api-method get",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-batch-import-api-keys",
+ id: "reference/api/admin-update-imported-api-key",
+ label: "Update Imported API Key",
+ className: "api-method patch",
+ },
+ {
+ type: "doc",
+ id: "reference/api/admin-batch-import-api-keys",
label: "Batch Import API Keys",
className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-list-issued-api-keys",
+ id: "reference/api/admin-list-issued-api-keys",
label: "List Issued API Keys",
className: "api-method get",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-issue-api-key",
+ id: "reference/api/admin-issue-api-key",
label: "Issue API Key",
className: "api-method post",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-get-issued-api-key",
+ id: "reference/api/admin-get-issued-api-key",
label: "Get Issued API Key",
className: "api-method get",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-update-issued-api-key",
+ id: "reference/api/admin-update-issued-api-key",
label: "Update Issued API Key",
className: "api-method patch",
},
{
type: "doc",
- id: "talos/reference/api/admin-plane-service-rotate-issued-api-key",
+ id: "reference/api/admin-rotate-issued-api-key",
label: "Rotate Issued API Key",
className: "api-method post",
},
@@ -92,24 +110,12 @@ const sidebar: SidebarsConfig = {
},
{
type: "category",
- label: "DataPlaneService",
+ label: "SelfService",
items: [
{
type: "doc",
- id: "talos/reference/api/data-plane-service-batch-verify-api-keys",
- label: "Batch Verify API Keys",
- className: "api-method post",
- },
- {
- type: "doc",
- id: "talos/reference/api/data-plane-service-self-revoke-api-key",
- label: "Self-Revoke API Key",
- className: "api-method post",
- },
- {
- type: "doc",
- id: "talos/reference/api/data-plane-service-verify-api-key",
- label: "Verify API Key",
+ id: "reference/api/revoke-api-key",
+ label: "Revoke API Key",
className: "api-method post",
},
],
diff --git a/docs/talos/reference/config.md b/docs/talos/reference/config.md
index 0d5f7139da..1468b1aaee 100644
--- a/docs/talos/reference/config.md
+++ b/docs/talos/reference/config.md
@@ -77,22 +77,22 @@ Cache configuration.
Credential configuration for API keys and derived tokens (JWT, macaroon).
-| Key | Type | Default | Env Var | Description |
-| ---------------------------------------------------- | ---------------- | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `credentials.api_keys.default_ttl` | string | — | `TALOS_CREDENTIALS_API_KEYS_DEFAULT_TTL` | Default API key TTL (duration string). |
-| `credentials.api_keys.max_ttl` | string | `8760h` | `TALOS_CREDENTIALS_API_KEYS_MAX_TTL` | Maximum age for API keys with timestamps. |
-| `credentials.api_keys.prefix.current` | string | `ory_ak` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_CURRENT` | Current prefix used for new API key generation. |
-| `credentials.api_keys.prefix.public_current` | string | — | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_CURRENT` | Current prefix used for new PUBLIC API key generation. |
-| `credentials.api_keys.prefix.public_retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_RETIRED` | Retired public prefixes accepted during verification for migration purposes. |
-| `credentials.api_keys.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_RETIRED` | Retired prefixes accepted during verification for migration purposes. |
-| `credentials.clock_skew` | string | `5m` | `TALOS_CREDENTIALS_CLOCK_SKEW` | Maximum clock skew tolerance for timestamp and token validation. |
-| `credentials.derived_tokens.default_ttl` | string | `1h` | `TALOS_CREDENTIALS_DERIVED_TOKENS_DEFAULT_TTL` | Default derived token TTL applied to both JWT and macaroon tokens when no explicit TTL is provided in the request (duration string) |
-| `credentials.derived_tokens.jwt.algorithm` | `EdDSA`, `RS256` | `EdDSA` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_ALGORITHM` | Token signing algorithm. |
-| `credentials.derived_tokens.jwt.signing_keys.urls` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEYS_URLS` | List of JWKS resources. |
-| `credentials.derived_tokens.macaroon.prefix.current` | string | `mc` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_CURRENT` | Current prefix used for new macaroon token generation. |
-| `credentials.derived_tokens.macaroon.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_RETIRED` | Retired prefixes accepted during macaroon verification for rotation purposes. |
-| `credentials.issuer` | string | — | `TALOS_CREDENTIALS_ISSUER` | Token issuer (iss claim) for derived tokens. (min 1 chars) |
-| `credentials.issuer_retired` | string[] | `[]` | `TALOS_CREDENTIALS_ISSUER_RETIRED` | Retired issuer URLs accepted during token verification. |
+| Key | Type | Default | Env Var | Description |
+| ---------------------------------------------------- | -------- | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials.api_keys.default_ttl` | string | — | `TALOS_CREDENTIALS_API_KEYS_DEFAULT_TTL` | Default API key TTL (duration string). |
+| `credentials.api_keys.max_ttl` | string | `8760h` | `TALOS_CREDENTIALS_API_KEYS_MAX_TTL` | Maximum age for API keys with timestamps. |
+| `credentials.api_keys.prefix.current` | string | `ory_ak` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_CURRENT` | Current prefix used for new API key generation. |
+| `credentials.api_keys.prefix.public_current` | string | — | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_CURRENT` | Current prefix used for new PUBLIC API key generation. |
+| `credentials.api_keys.prefix.public_retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_PUBLIC_RETIRED` | Retired public prefixes accepted during verification for migration purposes. |
+| `credentials.api_keys.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_RETIRED` | Retired prefixes accepted during verification for migration purposes. |
+| `credentials.clock_skew` | string | `5m` | `TALOS_CREDENTIALS_CLOCK_SKEW` | Maximum clock skew tolerance for timestamp and token validation. |
+| `credentials.derived_tokens.default_ttl` | string | `1h` | `TALOS_CREDENTIALS_DERIVED_TOKENS_DEFAULT_TTL` | Default derived token TTL applied to both JWT and macaroon tokens when no explicit TTL is provided in the request (duration string) |
+| `credentials.derived_tokens.jwt.signing_key_id` | string | "" | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEY_ID` | Preferred signing key ID (kid) to use when selecting a key from the configured JWKS. |
+| `credentials.derived_tokens.jwt.signing_keys.urls` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEYS_URLS` | List of JWKS resources. |
+| `credentials.derived_tokens.macaroon.prefix.current` | string | `mc` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_CURRENT` | Current prefix used for new macaroon token generation. |
+| `credentials.derived_tokens.macaroon.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_RETIRED` | Retired prefixes accepted during macaroon verification for rotation purposes. |
+| `credentials.issuer` | string | — | `TALOS_CREDENTIALS_ISSUER` | Token issuer (iss claim) for derived tokens. (min 1 chars) |
+| `credentials.issuer_retired` | string[] | `[]` | `TALOS_CREDENTIALS_ISSUER_RETIRED` | Retired issuer URLs accepted during token verification. |
## `db` (restart required)
From 23db08b43ced97d8a4eda2fba9e0096e5c9f8598 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Mon, 27 Apr 2026 12:53:20 +0200
Subject: [PATCH 4/8] chore: synchronize workspaces
---
.../quickstart/{preview.md => preview.mdx} | 79 ++++++++++---------
src/sidebar.ts | 24 +++++-
2 files changed, 65 insertions(+), 38 deletions(-)
rename docs/talos/quickstart/{preview.md => preview.mdx} (75%)
diff --git a/docs/talos/quickstart/preview.md b/docs/talos/quickstart/preview.mdx
similarity index 75%
rename from docs/talos/quickstart/preview.md
rename to docs/talos/quickstart/preview.mdx
index 5306920604..d74c156c90 100644
--- a/docs/talos/quickstart/preview.md
+++ b/docs/talos/quickstart/preview.mdx
@@ -6,12 +6,11 @@ title: Early-access quickstart
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
```
-# Early-access quickstart
+# Early-access preview quickstart
-Ory Talos is Ory's API key management service. This guide shows how to pull the public early-access
-commercial image, start a local Postgres-backed Ory Talos instance, and run the headline flows for
-issued and imported API keys. You only need Docker for the bring-up steps below; the `curl`
-examples are the preview baseline, and the Talos CLI is shown as an optional alternative.
+Talos is Ory's API key management service. This guide shows how to pull the public early-access commercial image, start a local
+Postgres-backed Talos instance, and run the headline flows for issued and imported API keys. You only need Docker for the bring-up
+steps below; the `curl` examples are the preview baseline, and the Talos CLI is shown as an optional alternative.
## Pull the image
@@ -56,8 +55,8 @@ db:
dsn: "postgres://talos:talos@talos-postgres:5432/talos?sslmode=disable"
secrets:
- default: { current: "preview-default-secret-minimum-32-chars-long" }
- hmac: { current: "preview-hmac-secret-minimum-32-chars-long" }
+ default: { current: "preview-default-secret-minimum-32-chars-long" }
+ hmac: { current: "preview-hmac-secret-minimum-32-chars-long" }
pagination: { current: "preview-pagination-secret-32-chars-min" }
cache: { type: "memory", ttl: "5m" }
@@ -67,8 +66,8 @@ log: { level: "info", format: "json" }
:::caution
-This config embeds the development EdDSA JWK from `deployments/docker/config/config.yaml`. Replace
-it before any non-preview use because the private key is published in the source tree.
+This config embeds the development EdDSA JWK from `deployments/docker/config/config.yaml`. Replace it before any non-preview use
+because the private key is published in the source tree.
:::
@@ -107,11 +106,11 @@ for i in $(seq 1 30); do
done
```
-The bring-up commands above are for local preview users. The executable API examples below are
-tested in CI against the commercial docs harness.
+The bring-up commands above are for local preview users. The executable API examples below are tested in CI against the same
+published image, running on the `talos-preview` Docker network.
-
-
+
+
Set the base URL for the local server:
@@ -121,8 +120,8 @@ export TALOS_URL="${TALOS_URL:-http://localhost:8080}"
## Issue an API key
-Create an issued key on the admin plane and save its secret for later steps. For the complete field
-reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+Create an issued key on the admin plane and save its secret for later steps. For the complete field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
@@ -130,12 +129,14 @@ reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-
```bash
-RESPONSE=$(talos keys issue "preview-issued-key" \
+RESPONSE=$(docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ keys issue "preview-issued-key" \
--actor preview-user \
--scopes "read:profile,write:profile" \
--ttl 720h \
--format json \
- -e "$TALOS_URL" 2>/dev/null)
+ -e "http://talos:8080" 2>/dev/null)
echo "$RESPONSE" | jq .
@@ -171,13 +172,12 @@ export KEY_ID=$KEY_ID
-The response returns `issued_api_key` metadata plus `secret`, which is shown only once. Store the
-secret securely.
+The response returns `issued_api_key` metadata plus `secret`, which is shown only once. Store the secret securely.
## Verify the issued key
-Send the issued key secret to the unified verify endpoint. For the full response fields and error
-codes, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+Send the issued key secret to the unified verify endpoint. For the full response fields and error codes, see the
+[VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
@@ -185,7 +185,9 @@ codes, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-ke
```bash
-talos keys verify "$API_SECRET" -e "$TALOS_URL"
+docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ keys verify "$API_SECRET" -e "http://talos:8080"
```
@@ -206,8 +208,8 @@ An active result includes `is_active: true` plus the key's actor, scopes, issuer
## Derive a JWT from the issued key
-Mint a short-lived JWT from the issued key with a custom claim. For the full request and response
-schema, see the [DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
+Mint a short-lived JWT from the issued key with a custom claim. For the full request and response schema, see the
+[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
@@ -215,12 +217,14 @@ schema, see the [DeriveToken API reference](../reference/api/admin-derive-token.
```bash
-RESPONSE=$(talos keys derive-token "$API_SECRET" \
+RESPONSE=$(docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ keys derive-token "$API_SECRET" \
--algorithm jwt \
--ttl 1h \
--claims '{"role":"preview-user","environment":"demo"}' \
--format json \
- -e "$TALOS_URL" 2>/dev/null)
+ -e "http://talos:8080" 2>/dev/null)
echo "$RESPONSE" | jq .
@@ -250,13 +254,12 @@ export JWT_TOKEN=$JWT_TOKEN
-The derived token inherits the parent key's permissions and returns as `token.token` with its own
-expiry metadata.
+The derived token inherits the parent key's permissions and returns as `token.token` with its own expiry metadata.
## Import an existing API key
-Import a raw key string into Talos without rotating the credential. For the complete field
-reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+Import a raw key string into Talos without rotating the credential. For the complete field reference, see the
+[ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
@@ -266,13 +269,15 @@ reference, see the [ImportAPIKey API reference](../reference/api/admin-import-ap
```bash
IMPORTED_RAW_KEY=sk_preview_demo_001
-RESPONSE=$(talos keys imported import "preview-imported-key" \
+RESPONSE=$(docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ keys imported import "preview-imported-key" \
--raw-key "$IMPORTED_RAW_KEY" \
--actor preview-import-user \
--scopes "payments:read,payments:write" \
--ttl 720h \
--format json \
- -e "$TALOS_URL" 2>/dev/null)
+ -e "http://talos:8080" 2>/dev/null)
echo "$RESPONSE" | jq .
@@ -309,13 +314,11 @@ export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
-Talos stores a cryptographic representation of the imported credential. The raw key is never
-returned after import.
+Talos stores a cryptographic representation of the imported credential. The raw key is never returned after import.
## Verify the imported key
-Imported keys use the same verify endpoint as issued keys. Talos detects the credential type
-automatically.
+Imported keys use the same verify endpoint as issued keys. Talos detects the credential type automatically.
@@ -323,7 +326,9 @@ automatically.
```bash
-talos keys verify "$IMPORTED_RAW_KEY" -e "$TALOS_URL"
+docker run --rm --network talos-preview \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ keys verify "$IMPORTED_RAW_KEY" -e "http://talos:8080"
```
diff --git a/src/sidebar.ts b/src/sidebar.ts
index 5527733ed3..b191ea74b5 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -9,6 +9,28 @@ import apiSidebar from "../docs/talos/reference/api/sidebar"
type SidebarItemsConfig = SidebarItemConfig[]
+function prefixSidebarIds(
+ items: SidebarItemsConfig,
+ prefix: string,
+): SidebarItemsConfig {
+ return items.map((item) => {
+ if (typeof item === "string") return `${prefix}${item}`
+ if (item.type === "doc") return { ...item, id: `${prefix}${item.id}` }
+ if (item.type === "category") {
+ const link =
+ item.link?.type === "doc"
+ ? { ...item.link, id: `${prefix}${item.link.id}` }
+ : item.link
+ return {
+ ...item,
+ link,
+ items: prefixSidebarIds(item.items as SidebarItemsConfig, prefix),
+ }
+ }
+ return item
+ })
+}
+
const homeLink: SidebarItem = {
type: "link",
href: "/welcome",
@@ -1033,7 +1055,7 @@ const talos: SidebarItemsConfig = [
type: "category",
label: "API",
link: { type: "doc", id: "talos/reference/api/ory-talos-api" },
- items: apiSidebar,
+ items: prefixSidebarIds(apiSidebar, "talos/"),
},
"talos/reference/config",
"talos/reference/error-codes",
From 34007ccd462392e1485ceee04307deec5b8313fb Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Mon, 27 Apr 2026 14:36:24 +0200
Subject: [PATCH 5/8] chore: synchronize workspaces
---
docs/talos/quickstart/preview.mdx | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/docs/talos/quickstart/preview.mdx b/docs/talos/quickstart/preview.mdx
index d74c156c90..a74039994c 100644
--- a/docs/talos/quickstart/preview.mdx
+++ b/docs/talos/quickstart/preview.mdx
@@ -6,12 +6,21 @@ title: Early-access quickstart
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
```
-# Early-access preview quickstart
+# Quickstart (early access)
Talos is Ory's API key management service. This guide shows how to pull the public early-access commercial image, start a local
Postgres-backed Talos instance, and run the headline flows for issued and imported API keys. You only need Docker for the bring-up
steps below; the `curl` examples are the preview baseline, and the Talos CLI is shown as an optional alternative.
+## Set up credentials
+
+1. Download `keyfile.json` from the email you received.
+2. Authenticate with Google Cloud:
+ ```bash
+ gcloud auth activate-service-account --key-file=keyfile.json
+ gcloud auth configure-docker europe-docker.pkg.dev
+ ```
+
## Pull the image
```bash
From 1fcf0dd01b951d401fbd2905ee48b470f1104e13 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Tue, 28 Apr 2026 09:55:23 +0200
Subject: [PATCH 6/8] chore: synchronize workspaces
---
docs/talos/concepts/architecture.md | 20 +-
docs/talos/concepts/credential-types.md | 9 +-
docs/talos/integrate/batch-operations.md | 5 +-
docs/talos/integrate/derive-tokens.md | 10 +-
docs/talos/integrate/error-handling.md | 4 +-
docs/talos/integrate/index.md | 20 +-
docs/talos/integrate/issue-and-verify.md | 18 +-
docs/talos/integrate/key-lifecycle.md | 4 +
docs/talos/integrate/sdk/curl.md | 8 +-
docs/talos/integrate/self-revocation.md | 23 +-
docs/talos/operate/configure.md | 2 +-
docs/talos/reference/api.json | 1631 -----------------
.../reference/api/admin-get-jwks.api.mdx | 4 +-
...e-batch-import-api-keys.RequestSchema.json | 102 --
...ice-batch-import-api-keys.StatusCodes.json | 189 --
...lane-service-batch-import-api-keys.api.mdx | 48 -
...delete-imported-api-key.ParamsDetails.json | 11 -
...delete-imported-api-key.RequestSchema.json | 1 -
...e-delete-imported-api-key.StatusCodes.json | 36 -
...ne-service-delete-imported-api-key.api.mdx | 42 -
...ne-service-derive-token.RequestSchema.json | 35 -
...lane-service-derive-token.StatusCodes.json | 51 -
.../admin-plane-service-derive-token.api.mdx | 46 -
...ce-get-imported-api-key.ParamsDetails.json | 11 -
...ce-get-imported-api-key.RequestSchema.json | 1 -
...vice-get-imported-api-key.StatusCodes.json | 129 --
...plane-service-get-imported-api-key.api.mdx | 41 -
...vice-get-issued-api-key.ParamsDetails.json | 10 -
...vice-get-issued-api-key.RequestSchema.json | 1 -
...ervice-get-issued-api-key.StatusCodes.json | 122 --
...n-plane-service-get-issued-api-key.api.mdx | 42 -
...-plane-service-get-jwks.RequestSchema.json | 1 -
...in-plane-service-get-jwks.StatusCodes.json | 42 -
.../api/admin-plane-service-get-jwks.api.mdx | 38 -
...-service-import-api-key.RequestSchema.json | 91 -
...ne-service-import-api-key.StatusCodes.json | 139 --
...admin-plane-service-import-api-key.api.mdx | 47 -
...e-service-issue-api-key.RequestSchema.json | 69 -
...ane-service-issue-api-key.StatusCodes.json | 136 --
.../admin-plane-service-issue-api-key.api.mdx | 48 -
...-list-imported-api-keys.ParamsDetails.json | 22 -
...-list-imported-api-keys.RequestSchema.json | 1 -
...ce-list-imported-api-keys.StatusCodes.json | 149 --
...ane-service-list-imported-api-keys.api.mdx | 42 -
...ce-list-issued-api-keys.ParamsDetails.json | 22 -
...ce-list-issued-api-keys.RequestSchema.json | 1 -
...vice-list-issued-api-keys.StatusCodes.json | 138 --
...plane-service-list-issued-api-keys.api.mdx | 42 -
...-service-revoke-api-key.ParamsDetails.json | 10 -
...-service-revoke-api-key.RequestSchema.json | 34 -
...ne-service-revoke-api-key.StatusCodes.json | 36 -
...admin-plane-service-revoke-api-key.api.mdx | 45 -
...e-rotate-issued-api-key.ParamsDetails.json | 11 -
...e-rotate-issued-api-key.RequestSchema.json | 77 -
...ice-rotate-issued-api-key.StatusCodes.json | 223 ---
...lane-service-rotate-issued-api-key.api.mdx | 52 -
...e-update-issued-api-key.ParamsDetails.json | 10 -
...e-update-issued-api-key.RequestSchema.json | 53 -
...ice-update-issued-api-key.StatusCodes.json | 122 --
...lane-service-update-issued-api-key.api.mdx | 46 -
.../api/batch-verify-api-keys.api.mdx | 45 +
...e-batch-verify-api-keys.RequestSchema.json | 30 -
...ice-batch-verify-api-keys.StatusCodes.json | 121 --
...lane-service-batch-verify-api-keys.api.mdx | 48 -
...ice-self-revoke-api-key.RequestSchema.json | 36 -
...rvice-self-revoke-api-key.StatusCodes.json | 40 -
...-plane-service-self-revoke-api-key.api.mdx | 48 -
...-service-verify-api-key.RequestSchema.json | 21 -
...ne-service-verify-api-key.StatusCodes.json | 109 --
.../data-plane-service-verify-api-key.api.mdx | 55 -
.../reference/api/ory-talos-api.info.mdx | 4 +-
docs/talos/reference/api/sidebar.ts | 12 +
.../reference/api/verify-api-key.api.mdx | 42 +
73 files changed, 189 insertions(+), 4845 deletions(-)
delete mode 100644 docs/talos/reference/api.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
create mode 100644 docs/talos/reference/api/batch-verify-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
delete mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
delete mode 100644 docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
delete mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
delete mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
delete mode 100644 docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
create mode 100644 docs/talos/reference/api/verify-api-key.api.mdx
diff --git a/docs/talos/concepts/architecture.md b/docs/talos/concepts/architecture.md
index f82fc1f563..98fa68ec94 100644
--- a/docs/talos/concepts/architecture.md
+++ b/docs/talos/concepts/architecture.md
@@ -18,7 +18,10 @@ Endpoints: `/v2/admin/`
The data plane handles high-throughput read operations: key verification, batch verification, and self-revocation. It is designed
for low-latency edge deployment.
-Endpoints: `/v2/admin/apiKeys:verify`, `/v2/admin/apiKeys:batchVerify`, `/v2/apiKeys:selfRevoke`
+Primary endpoints: `/v2/apiKeys:verify`, `/v2/apiKeys:batchVerify`, `/v2/apiKeys:selfRevoke`
+
+Admin-scoped verification endpoints also exist for operator workflows, including `/v2/admin/apiKeys:verify` and
+`/v2/admin/apiKeys:batchVerify`, but the self-service paths are the primary data-plane surface for credential holders.
## Request flow
@@ -28,7 +31,7 @@ Client --> Data Plane --> Cache (hit?) --> Database --> Response
+-- cache hit ---------------+
```
-1. Client sends credential to `POST /v2/admin/apiKeys:verify`
+1. Client sends credential to `POST /v2/apiKeys:verify`
2. Talos identifies the credential type (generated, imported, JWT, macaroon)
3. For generated keys, the UUID is extracted from the token identifier
4. For imported keys, a tenant-scoped SHA-512/256 hash is computed
@@ -162,11 +165,16 @@ The cache layer reduces database load on the verification path:
### Crypto
-Talos supports multiple signing algorithms:
+Talos supports multiple JWT signing algorithms and a separate API key hashing mechanism:
+
+- **JWT signing algorithms**
+- `Ed25519 (EdDSA)` -- default, fastest signing and smallest keys
+- `RSA-2048/4096 (RS256)` -- legacy compatibility
+- **API key hashing**
+- `HMAC-SHA256` -- used for API key revocation checks (\<1ms with constant-time comparison)
-- **Ed25519 (EdDSA)** -- default, fastest signing and smallest keys
-- **RSA-2048/4096 (RS256)** -- legacy compatibility
-- **HMAC-SHA256** -- used for API key revocation checks (\<1ms with constant-time comparison)
+The JWT signing algorithm is determined per JWK by its `alg` field, so one JWKS can contain keys for multiple signing algorithms
+at the same time.
### Observability
diff --git a/docs/talos/concepts/credential-types.md b/docs/talos/concepts/credential-types.md
index 813849a668..ae01b7d3ca 100644
--- a/docs/talos/concepts/credential-types.md
+++ b/docs/talos/concepts/credential-types.md
@@ -23,7 +23,7 @@ External credentials (Stripe, GitHub, etc.) stored by hash. Any string format ac
## Derived JWTs
Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg` field in the JWK (EdDSA or
-RS256). Can be verified independently using the JWKS endpoint (`GET /v2/admin/derivedKeys/jwks.json`). Claims include `key_id`,
+RS256). Can be verified independently using the JWKS endpoint (`GET /v2/admin/.well-known/jwks.json`). Claims include `key_id`,
`actor_id`, scopes, and expiration.
## Derived macaroons
@@ -32,6 +32,7 @@ Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support sc
## Credential routing
-When a credential is submitted to `/v2/admin/apiKeys:verify`, Talos identifies the type automatically by its format and routes it
-to the appropriate verification handler. See the [credential routing table](../reference/token-format.md#credential-routing) for
-the full format-to-type mapping and lookup methods.
+When a credential is submitted to `/v2/apiKeys:verify`, Talos identifies the type automatically by its format and routes it to the
+appropriate verification handler. The admin-scoped verify endpoint uses the same credential routing logic. See the
+[credential routing table](../reference/token-format.md#credential-routing) for the full format-to-type mapping and lookup
+methods.
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.md
index 4dd4bcee13..5b9af68f86 100644
--- a/docs/talos/integrate/batch-operations.md
+++ b/docs/talos/integrate/batch-operations.md
@@ -77,7 +77,7 @@ talos keys batch-verify "$KEY1" "$KEY2" "invalid-key-for-testing" \
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
-H "Content-Type: application/json" \
-d "{
\"requests\": [
@@ -91,6 +91,9 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
+The current `talos keys batch-verify` CLI command uses the admin-scoped batch verify API under the hood. The curl example above
+shows the self-service data-plane endpoint.
+
### Response format
The response contains a `results` array. Each element has the same fields as a single
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.md
index 5d36301868..4db8a03217 100644
--- a/docs/talos/integrate/derive-tokens.md
+++ b/docs/talos/integrate/derive-tokens.md
@@ -107,6 +107,9 @@ The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN
optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
+For HTTP API requests, `ttl` accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo` in addition to
+standard Go durations. The current CLI `--ttl` flag still expects standard Go durations such as `1h` or `30m`.
+
### Response
The response contains a `token` object with `token.token` (the derived token string), `token.expire_time`, `token.scopes`, and
@@ -130,7 +133,7 @@ talos keys verify "$JWT_TOKEN" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$JWT_TOKEN\"}" | jq .
```
@@ -138,6 +141,9 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+The current `talos keys verify` CLI command uses the admin-scoped verify API under the hood. The curl example above shows the
+self-service data-plane endpoint.
+
The verification response includes the token's scopes, actor, and metadata from the parent key.
## Derive a macaroon
@@ -198,7 +204,7 @@ talos jwk get -e "$TALOS_URL"
```bash
-curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
+curl -s "$TALOS_URL/v2/admin/.well-known/jwks.json" | jq .
```
diff --git a/docs/talos/integrate/error-handling.md b/docs/talos/integrate/error-handling.md
index 1986a5925f..2176483c75 100644
--- a/docs/talos/integrate/error-handling.md
+++ b/docs/talos/integrate/error-handling.md
@@ -37,8 +37,8 @@ Error responses use this structure:
## Verification errors
-The verify endpoint (`POST /v2/admin/apiKeys:verify`) returns errors differently from admin endpoints. Instead of an HTTP error,
-it returns `200 OK` with `is_active: false` and a structured error code:
+The verify endpoints (`POST /v2/apiKeys:verify` and `POST /v2/admin/apiKeys:verify`) return errors differently from most admin
+endpoints. Instead of an HTTP error, they return `200 OK` with `is_active: false` and a structured error code:
```json
{
diff --git a/docs/talos/integrate/index.md b/docs/talos/integrate/index.md
index 4713b7ac01..4643473774 100644
--- a/docs/talos/integrate/index.md
+++ b/docs/talos/integrate/index.md
@@ -15,16 +15,16 @@ arrives.
## Common workflows
-| Task | Endpoint | Guide |
-| --------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
-| Issue a key and verify it | `POST /v2/admin/issuedApiKeys`, `POST /v2/admin/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
-| Import keys from another system | `POST /v2/admin/importedApiKeys` | [Import keys](import-keys.md) |
-| Mint short-lived JWT or macaroon tokens | `POST /v2/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
-| Verify many credentials at once | `POST /v2/admin/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
-| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
-| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
-| Let key holders revoke their own key | `POST /v2/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
-| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
+| Task | Endpoint | Guide |
+| --------------------------------------- | --------------------------------------------------------- | --------------------------------------- |
+| Issue a key and verify it | `POST /v2/admin/issuedApiKeys`, `POST /v2/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
+| Import keys from another system | `POST /v2/admin/importedApiKeys` | [Import keys](import-keys.md) |
+| Mint short-lived JWT or macaroon tokens | `POST /v2/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
+| Verify many credentials at once | `POST /v2/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
+| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
+| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
+| Let key holders revoke their own key | `POST /v2/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
+| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
## Authentication
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.md
index c9be80a77d..784aea38b3 100644
--- a/docs/talos/integrate/issue-and-verify.md
+++ b/docs/talos/integrate/issue-and-verify.md
@@ -75,6 +75,9 @@ The key fields are `name` (human-readable label), `actor_id` (key actor), and op
`rate_limit_policy`. For the complete field reference, see the
[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+For HTTP API requests, `ttl` also accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo`. The
+current CLI `--ttl` flag examples still use standard Go durations such as `720h` and `1h30m`.
+
### Response fields
The response contains two top-level fields:
@@ -102,7 +105,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -110,12 +113,15 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+The current `talos keys verify` CLI command uses the admin-scoped verify API under the hood. The curl example above shows the
+self-service data-plane endpoint that credential holders can call directly.
+
### Verification response
-The response includes `is_active` (boolean), `key_id`, `actor_id`, `scopes`, `metadata`, and `expire_time` when valid. When
-`is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled (Commercial),
-the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the complete
-field reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+The response includes `is_active` (boolean), `key_id`, `actor_id`, `issuer`, `scopes`, `metadata`, and `expire_time` when valid.
+When `is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled
+(Commercial), the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For
+the complete field reference, see the [VerifyAPIKey API reference](../reference/api/verify-api-key.api.mdx).
### Verification error codes
@@ -129,7 +135,7 @@ rate limit quota is exhausted). For the complete list, see the
Verification results are cached for performance. After revoking a key, you can bypass the cache for immediate consistency:
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{"credential":"sk_..."}'
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.md
index 85cd392e64..01cc5c0a63 100644
--- a/docs/talos/integrate/key-lifecycle.md
+++ b/docs/talos/integrate/key-lifecycle.md
@@ -55,6 +55,10 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+When you set `ttl` on issue or import requests, the HTTP API accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and
+compounds like `1y6mo` in addition to standard Go durations. The current CLI `--ttl` flags still expect standard Go duration
+strings; see the [configuration reference](../reference/config.md) for the canonical duration format summary.
+
## Update key metadata
Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the secret:
diff --git a/docs/talos/integrate/sdk/curl.md b/docs/talos/integrate/sdk/curl.md
index e6a7c53239..f55fe58946 100644
--- a/docs/talos/integrate/sdk/curl.md
+++ b/docs/talos/integrate/sdk/curl.md
@@ -184,7 +184,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
```bash
-curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
+curl -s "$TALOS_URL/v2/admin/.well-known/jwks.json" | jq .
```
## Data plane
@@ -194,7 +194,7 @@ curl -s "$TALOS_URL/v2/admin/derivedKeys/jwks.json" | jq .
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -204,7 +204,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
@@ -215,7 +215,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:batchVerify" \
+curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
-H "Content-Type: application/json" \
-d "{
\"requests\": [
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.md
index 7413439c14..8cd127b4b4 100644
--- a/docs/talos/integrate/self-revocation.md
+++ b/docs/talos/integrate/self-revocation.md
@@ -60,6 +60,27 @@ echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
+## Verify your own credential
+
+Use the data-plane verify endpoint when a credential holder needs to check a key without admin credentials. The admin-plane verify
+endpoint returns the same response shape and is still useful for operator workflows.
+
+
+
+
+
+
+```bash
+curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+ -H "Content-Type: application/json" \
+ -d "{\"credential\":\"$SELF_REVOKE_SECRET\"}" | jq .
+```
+
+
+
+
+For the complete response fields, see the [Verify API Key reference](../reference/api/verify-api-key.api.mdx).
+
Send the full key secret as proof of possession:
@@ -106,7 +127,7 @@ echo "Self-revocation confirmed"
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$SELF_REVOKE_SECRET\"}")
diff --git a/docs/talos/operate/configure.md b/docs/talos/operate/configure.md
index 25fe5d5d51..dae9c923b0 100644
--- a/docs/talos/operate/configure.md
+++ b/docs/talos/operate/configure.md
@@ -68,7 +68,7 @@ credentials:
current: "talos"
derived_tokens:
jwt:
- algorithm: "EdDSA"
+ signing_key_id: "" # Optional JWKS kid hint; defaults to the first usable signing key
default_ttl: "1h"
signing_keys:
urls:
diff --git a/docs/talos/reference/api.json b/docs/talos/reference/api.json
deleted file mode 100644
index 97e03892cb..0000000000
--- a/docs/talos/reference/api.json
+++ /dev/null
@@ -1,1631 +0,0 @@
-{
- "components": {
- "schemas": {
- "StaticCredentialsAdminRevokeAPIKeyBody": {
- "properties": {
- "description": {
- "description": "Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.",
- "type": "string"
- },
- "reason": {
- "$ref": "#/components/schemas/v2RevocationReason"
- }
- },
- "type": "object"
- },
- "StaticCredentialsAdminRotateIssuedAPIKeyBody": {
- "properties": {
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "metadata": {
- "title": "metadata for the new API key (inherits from old key if not provided)",
- "type": "object"
- },
- "name": {
- "title": "name for the new API key (inherits from old key if not provided)",
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "title": "scopes for the new API key (inherits from old key if not provided)",
- "type": "array"
- },
- "update_mask": {
- "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
- "type": "string"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "type": "object"
- },
- "StaticCredentialsAdminUpdateImportedAPIKeyBody": {
- "properties": {
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "metadata": {
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "update_mask": {
- "title": "AIP-134 partial update mask",
- "type": "string"
- }
- },
- "type": "object"
- },
- "StaticCredentialsAdminUpdateIssuedAPIKeyBody": {
- "properties": {
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "metadata": {
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "update_mask": {
- "type": "string"
- }
- },
- "type": "object"
- },
- "protobufAny": {
- "additionalProperties": {},
- "properties": {
- "@type": {
- "type": "string"
- }
- },
- "type": "object"
- },
- "protobufNullValue": {
- "default": "NULL_VALUE",
- "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value.",
- "enum": ["NULL_VALUE"],
- "type": "string"
- },
- "rpcStatus": {
- "properties": {
- "code": {
- "format": "int32",
- "type": "integer"
- },
- "details": {
- "items": {
- "$ref": "#/components/schemas/protobufAny"
- },
- "type": "array"
- },
- "message": {
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2BatchImportAPIKeysRequest": {
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "properties": {
- "requests": {
- "items": {
- "$ref": "#/components/schemas/v2ImportAPIKeyRequest"
- },
- "title": "Keys to import",
- "type": "array"
- }
- },
- "type": "object"
- },
- "v2BatchImportAPIKeysResponse": {
- "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
- "properties": {
- "failure_count": {
- "format": "int32",
- "type": "integer"
- },
- "results": {
- "items": {
- "$ref": "#/components/schemas/v2BatchImportResult"
- },
- "type": "array"
- },
- "success_count": {
- "format": "int32",
- "type": "integer"
- }
- },
- "type": "object"
- },
- "v2BatchImportErrorCode": {
- "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
- "enum": [
- "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
- "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
- "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
- "BATCH_IMPORT_ERROR_INTERNAL"
- ],
- "type": "string"
- },
- "v2BatchImportResult": {
- "description": "BatchImportResult contains the result for one key in a batch import request.",
- "properties": {
- "error_code": {
- "$ref": "#/components/schemas/v2BatchImportErrorCode"
- },
- "error_message": {
- "title": "Human-readable failure reason",
- "type": "string"
- },
- "imported_api_key": {
- "$ref": "#/components/schemas/v2ImportedAPIKey"
- },
- "index": {
- "format": "int32",
- "title": "Zero-based index in request.requests",
- "type": "integer"
- }
- },
- "type": "object"
- },
- "v2BatchVerifyAPIKeysRequest": {
- "properties": {
- "requests": {
- "items": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
- },
- "type": "array"
- }
- },
- "type": "object"
- },
- "v2BatchVerifyAPIKeysResponse": {
- "properties": {
- "results": {
- "items": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
- },
- "type": "array"
- }
- },
- "type": "object"
- },
- "v2DeriveTokenRequest": {
- "properties": {
- "algorithm": {
- "$ref": "#/components/schemas/v2TokenAlgorithm"
- },
- "credential": {
- "title": "The API key secret (issued or imported) to derive a token from",
- "type": "string"
- },
- "custom_claims": {
- "type": "object"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- }
- },
- "title": "Token derivation messages",
- "type": "object"
- },
- "v2DeriveTokenResponse": {
- "properties": {
- "token": {
- "$ref": "#/components/schemas/v2Token"
- }
- },
- "type": "object"
- },
- "v2GetJWKSResponse": {
- "properties": {
- "jwks": {
- "title": "JSON Web Key Set",
- "type": "object"
- }
- },
- "type": "object"
- },
- "v2IPRestriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- },
- "type": "object"
- },
- "v2ImportAPIKeyRequest": {
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "properties": {
- "actor_id": {
- "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
- "type": "string"
- },
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "metadata": {
- "title": "Additional metadata (OPTIONAL)",
- "type": "object"
- },
- "name": {
- "title": "Human-readable name (REQUIRED)",
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "raw_key": {
- "title": "The actual key string to import (REQUIRED)",
- "type": "string"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "title": "Scopes for the imported key (OPTIONAL)",
- "type": "array"
- },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
- "type": "object"
- },
- "v2ImportAPIKeyResponse": {
- "properties": {
- "imported_api_key": {
- "$ref": "#/components/schemas/v2ImportedAPIKey"
- }
- },
- "type": "object"
- },
- "v2ImportedAPIKey": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": {
- "type": "string"
- },
- "create_time": {
- "format": "date-time",
- "type": "string"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": {
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "$ref": "#/components/schemas/v2RevocationReason"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "status": {
- "$ref": "#/components/schemas/v2KeyStatus"
- },
- "update_time": {
- "format": "date-time",
- "type": "string"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "type": "object"
- },
- "v2IssueAPIKeyRequest": {
- "properties": {
- "actor_id": {
- "type": "string"
- },
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "metadata": {
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "type": "object"
- },
- "v2IssueAPIKeyResponse": {
- "properties": {
- "issued_api_key": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- },
- "secret": {
- "title": "Only returned on creation",
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2IssuedAPIKey": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": {
- "type": "string"
- },
- "create_time": {
- "format": "date-time",
- "type": "string"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "ip_restriction": {
- "$ref": "#/components/schemas/v2IPRestriction"
- },
- "key_id": {
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": {
- "type": "object"
- },
- "name": {
- "type": "string"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "$ref": "#/components/schemas/v2RevocationReason"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "status": {
- "$ref": "#/components/schemas/v2KeyStatus"
- },
- "update_time": {
- "format": "date-time",
- "type": "string"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "type": "object"
- },
- "v2KeyStatus": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string"
- },
- "v2KeyVisibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string"
- },
- "v2ListImportedAPIKeysResponse": {
- "properties": {
- "imported_api_keys": {
- "items": {
- "$ref": "#/components/schemas/v2ImportedAPIKey"
- },
- "title": "List of imported keys",
- "type": "array"
- },
- "next_page_token": {
- "title": "Token for fetching the next page (empty if no more results)",
- "type": "string"
- }
- },
- "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
- "type": "object"
- },
- "v2ListIssuedAPIKeysResponse": {
- "properties": {
- "issued_api_keys": {
- "items": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- },
- "type": "array"
- },
- "next_page_token": {
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2RateLimitPolicy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2RevocationReason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string"
- },
- "v2RotateIssuedAPIKeyResponse": {
- "properties": {
- "issued_api_key": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- },
- "old_issued_api_key": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- },
- "secret": {
- "title": "secret is the new API key secret (only returned once, never retrievable again)",
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2SelfRevokeAPIKeyRequest": {
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "properties": {
- "credential": {
- "title": "Full API key secret or imported key (REQUIRED)",
- "type": "string"
- },
- "reason": {
- "$ref": "#/components/schemas/v2RevocationReason"
- }
- },
- "type": "object"
- },
- "v2SelfRevokeAPIKeyResponse": {
- "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
- "type": "object"
- },
- "v2Token": {
- "properties": {
- "claims": {
- "type": "object"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "token": {
- "type": "string"
- }
- },
- "title": "Token represents a short-lived derived token (JWT or Macaroon)",
- "type": "object"
- },
- "v2TokenAlgorithm": {
- "default": "TOKEN_ALGORITHM_UNSPECIFIED",
- "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
- "enum": [
- "TOKEN_ALGORITHM_UNSPECIFIED",
- "TOKEN_ALGORITHM_JWT",
- "TOKEN_ALGORITHM_MACAROON"
- ],
- "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
- "type": "string"
- },
- "v2VerificationErrorCode": {
- "default": "VERIFICATION_ERROR_UNSPECIFIED",
- "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
- "enum": [
- "VERIFICATION_ERROR_UNSPECIFIED",
- "VERIFICATION_ERROR_INVALID_FORMAT",
- "VERIFICATION_ERROR_EXPIRED",
- "VERIFICATION_ERROR_REVOKED",
- "VERIFICATION_ERROR_NOT_FOUND",
- "VERIFICATION_ERROR_SIGNATURE_INVALID",
- "VERIFICATION_ERROR_INTERNAL",
- "VERIFICATION_ERROR_IP_NOT_ALLOWED",
- "VERIFICATION_ERROR_RATE_LIMITED"
- ],
- "title": "VerificationErrorCode provides type-safe error codes for verification failures",
- "type": "string"
- },
- "v2VerifyAPIKeyRequest": {
- "properties": {
- "credential": {
- "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
- "type": "string"
- }
- },
- "type": "object"
- },
- "v2VerifyAPIKeyResponse": {
- "properties": {
- "actor_id": {
- "type": "string"
- },
- "error_code": {
- "$ref": "#/components/schemas/v2VerificationErrorCode"
- },
- "error_message": {
- "title": "Human-readable error message (only set if is_active=false)",
- "type": "string"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "is_active": {
- "type": "boolean"
- },
- "issuer": {
- "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
- "type": "string"
- },
- "key_id": {
- "type": "string"
- },
- "metadata": {
- "type": "object"
- },
- "rate_limit_policy": {
- "$ref": "#/components/schemas/v2RateLimitPolicy"
- },
- "rate_limit_remaining": {
- "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
- "format": "int64",
- "type": "string"
- },
- "rate_limit_reset_time": {
- "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
- "format": "date-time",
- "type": "string"
- },
- "scopes": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "visibility": {
- "$ref": "#/components/schemas/v2KeyVisibility"
- }
- },
- "type": "object"
- }
- }
- },
- "info": {
- "description": "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.\n\nThe API is split into two services:\n\n- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification\n- **SelfService** — self-service revocation for credential holders",
- "title": "Ory Talos API",
- "version": "2.0"
- },
- "openapi": "3.0.3",
- "paths": {
- "/v2/admin/.well-known/jwks.json": {
- "get": {
- "description": "Returns the JSON Web Key Set for token verification. Provides the public\nkeys needed to verify JWT tokens issued by this service. Keys are loaded\nfrom configuration (file://, https://, or base64:// URIs). Follows the\nJWKS standard (RFC 7517).\n\n```http\nGET /v2/admin/.well-known/jwks.json\n```",
- "operationId": "AdminGetJWKS",
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2GetJWKSResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Get JWKS",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/apiKeys/{key_id}:revoke": {
- "post": {
- "description": "Immediately revokes an API key (issued or imported). Once revoked, the key\ncan no longer be used for authentication. This operation is irreversible.\nRevoked keys are retained for audit purposes.\n\n```http\nPOST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke\n{\n \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"\n}\n```",
- "operationId": "AdminRevokeAPIKey",
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/StaticCredentialsAdminRevokeAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- },
- "description": "A successful response."
- },
- "204": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "API key revoked successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Revoke API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/apiKeys:batchVerify": {
- "post": {
- "description": "Verifies multiple credentials in a single request. Efficiently verifies up\nto 100 credentials in parallel. Each credential is verified independently;\npartial failures are returned. Admin access only.\n\n```http\nPOST /v2/admin/apiKeys:batchVerify\n{\n \"requests\": [\n {\"credential\": \"sk_live_abc123...\"},\n {\"credential\": \"eyJhbGciOiJFZERTQSI...\"}\n ]\n}\n```",
- "operationId": "AdminBatchVerifyAPIKeys",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchVerifyAPIKeysRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchVerifyAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Batch Verify API Keys",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/apiKeys:derive": {
- "post": {
- "description": "Mints a short-lived JWT or Macaroon token from an API key. Works with both\nissued and imported keys. The derived token inherits the permissions of the\nparent API key.\n\n```http\nPOST /v2/admin/apiKeys:derive\n{\n \"credential\": \"eyJhbGciOiJFZERTQSI...\",\n \"ttl\": \"1h\"\n}\n```",
- "operationId": "AdminDeriveToken",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2DeriveTokenRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2DeriveTokenResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Derive Token",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/apiKeys:verify": {
- "post": {
- "description": "Verifies a single API key or derived token. Validates the credential's\nsignature, expiration, and revocation status. Works with any credential\ntype (issued keys, imported keys, JWT, macaroon). The verification result\nincludes decoded claims and metadata — admin access only.\n\nCache Control (HTTP Headers):\n - Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup\n - Cache-Control: no-store - Bypasses cache read AND write (never cached)\n - Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)\n\n```http\nPOST /v2/admin/apiKeys:verify\n{\n \"credential\": \"sk_live_abc123...\"\n}\n```",
- "operationId": "AdminVerifyAPIKey",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Verify API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/importedApiKeys": {
- "get": {
- "description": "Lists all imported keys with filtering. Returns imported keys only (not\nissued keys). Supports pagination and AIP-160 filter expressions.\n\n```http\nGET /v2/admin/importedApiKeys?page_size=50\u0026filter=status%3DKEY_STATUS_ACTIVE\n```",
- "operationId": "AdminListImportedAPIKeys",
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": {
- "format": "int32",
- "type": "integer"
- }
- },
- {
- "description": "Cursor token for pagination (OPTIONAL)",
- "in": "query",
- "name": "page_token",
- "schema": {
- "type": "string"
- }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ListImportedAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "List Imported API Keys",
- "tags": ["StaticCredentials"]
- },
- "post": {
- "description": "Imports an external API key into the system. Allows importing keys from\nlegacy systems or external providers. The raw key is hashed and stored\nsecurely (HMAC). Imported keys support token derivation (JWT/Macaroon)\nlike issued keys.\n\n```http\nPOST /v2/admin/importedApiKeys\n{\n \"raw_key\": \"sk_live_abc123xyz\",\n \"name\": \"Imported Stripe Key\",\n \"actor_id\": \"user_123\"\n}\n```",
- "operationId": "AdminImportAPIKey",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ImportAPIKeyRequest"
- }
- }
- },
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ImportAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "API key imported successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Import API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/importedApiKeys/{key_id}": {
- "delete": {
- "description": "Permanently deletes an imported key (hard delete). The key is removed from\nthe database. Use RevokeAPIKey for soft deletion (recommended).\n\n```http\nDELETE /v2/admin/importedApiKeys/{key_id}\n```",
- "operationId": "AdminDeleteImportedAPIKey",
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "type": "object"
- }
- }
- },
- "description": "A successful response."
- },
- "204": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "Imported key deleted successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Delete Imported API Key",
- "tags": ["StaticCredentials"]
- },
- "get": {
- "description": "Retrieves details about a specific imported key. Returns metadata about\nthe imported key. The original raw key is never returned.\n\n```http\nGET /v2/admin/importedApiKeys/{key_id}\n```",
- "operationId": "AdminGetImportedAPIKey",
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ImportedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Get Imported API Key",
- "tags": ["StaticCredentials"]
- },
- "patch": {
- "description": "Updates metadata, scopes, or rate limits of an imported key. Supports\npartial updates via update_mask (AIP-134).\n\n```http\nPATCH /v2/admin/importedApiKeys/{key_id}\n{\n \"name\": \"New name\",\n \"update_mask\": \"name\"\n}\n```",
- "operationId": "AdminUpdateImportedAPIKey",
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED, path param)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/StaticCredentialsAdminUpdateImportedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ImportedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Update Imported API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/importedApiKeys:batchImport": {
- "post": {
- "description": "Imports up to 1000 external API keys in one request. Returns per-item\nresults. If at least one item succeeds, response is 200 OK. If all items\nfail, the endpoint returns a non-200 error.\n\n```http\nPOST /v2/admin/importedApiKeys:batchImport\n{\n \"requests\": [\n {\"raw_key\": \"sk_live_abc\", \"name\": \"Stripe key\", \"actor_id\": \"user_1\"},\n {\"raw_key\": \"ghp_xyz\", \"name\": \"GitHub PAT\", \"actor_id\": \"user_2\"}\n ]\n}\n```",
- "operationId": "AdminBatchImportAPIKeys",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchImportAPIKeysRequest"
- }
- }
- },
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchImportAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "Batch import completed. Check per-item results for individual status."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Batch Import API Keys",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/issuedApiKeys": {
- "get": {
- "description": "Lists issued API keys with optional filtering. Supports cursor-based\npagination and AIP-160 filter expressions. Returns only issued\n(generated) API keys; use ListImportedAPIKeys for imported keys.\n\n```http\nGET /v2/admin/issuedApiKeys?page_size=50\u0026filter=actor_id%3D%22user_123%22\n```",
- "operationId": "AdminListIssuedAPIKeys",
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": {
- "format": "int32",
- "type": "integer"
- }
- },
- {
- "description": "Cursor token for pagination",
- "in": "query",
- "name": "page_token",
- "schema": {
- "type": "string"
- }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2ListIssuedAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "List Issued API Keys",
- "tags": ["StaticCredentials"]
- },
- "post": {
- "description": "Creates a new API key for a given actor. The secret is returned only once\nin the response and cannot be retrieved later. Keys can be scoped with\nspecific permissions and have optional expiration.\n\n```http\nPOST /v2/admin/issuedApiKeys\n{\n \"name\": \"production-service\",\n \"actor_id\": \"user_123\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\"\n}\n```",
- "operationId": "AdminIssueAPIKey",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2IssueAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2IssueAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "API key issued successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Issue API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/issuedApiKeys/{key_id}": {
- "get": {
- "description": "Retrieves details about a specific issued API key including its status,\nscopes, expiration, and usage statistics. The secret is never returned.\n\n```http\nGET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ\n```",
- "operationId": "AdminGetIssuedAPIKey",
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Get Issued API Key",
- "tags": ["StaticCredentials"]
- },
- "patch": {
- "description": "Updates metadata, scopes, or rate limits of an issued key without rotating\nthe secret. Use RotateIssuedAPIKey to change the secret.\n\n```http\nPATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ\n{\n \"scopes\": [\"read\"],\n \"update_mask\": \"scopes\"\n}\n```",
- "operationId": "AdminUpdateIssuedAPIKey",
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/StaticCredentialsAdminUpdateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Update Issued API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/admin/issuedApiKeys/{key_id}:rotate": {
- "post": {
- "description": "Generates a new secret for an issued API key. Creates a new API key with a\nnew key_id and secret, and immediately revokes the old key. This is the\nrecommended way to update scopes, metadata, or rotate credentials.\n\nFor zero-downtime rotation, use this workflow instead:\n 1. IssueAPIKey with new credentials\n 2. Deploy new secret to all services\n 3. Verify new secret works everywhere\n 4. RevokeAPIKey to remove the old key\n\n```http\nPOST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate\n{\n \"scopes\": [\"read\"]\n}\n```",
- "operationId": "AdminRotateIssuedAPIKey",
- "parameters": [
- {
- "description": "key_id is the ID of the existing API key to rotate",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": {
- "type": "string"
- }
- }
- ],
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/StaticCredentialsAdminRotateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2RotateIssuedAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": {
- "application/json": {
- "schema": {}
- }
- },
- "description": "API key rotated successfully. New key issued, old key revoked."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Rotate Issued API Key",
- "tags": ["StaticCredentials"]
- }
- },
- "/v2/apiKeys:batchVerify": {
- "post": {
- "description": "Verifies multiple credentials in a single request. Efficiently verifies up\nto 100 credentials in parallel. Each credential is verified independently;\npartial failures are returned in the response.\n\n```http\nPOST /v2/apiKeys:batchVerify\n{\n \"requests\": [\n {\"credential\": \"sk_live_abc123...\"},\n {\"credential\": \"sk_live_xyz789...\"}\n ]\n}\n```",
- "operationId": "BatchVerifyAPIKeys",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchVerifyAPIKeysRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2BatchVerifyAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Batch Verify API Keys",
- "tags": ["SelfService"]
- }
- },
- "/v2/apiKeys:selfRevoke": {
- "post": {
- "description": "Allows an API key holder to revoke their own key. The caller must provide\nthe full API key secret as proof of possession. Supports issued API keys\nand imported keys. JWT and macaroon tokens cannot be self-revoked (they\nare stateless).\n\nThe PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation\n(admin-only).\n\n```http\nPOST /v2/apiKeys:selfRevoke\n{\n \"credential\": \"sk_live_abc123...\",\n \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"\n}\n```",
- "operationId": "RevokeAPIKey",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2SelfRevokeAPIKeyRequest"
- }
- }
- },
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2SelfRevokeAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Revoke API Key",
- "tags": ["SelfService"]
- }
- },
- "/v2/apiKeys:verify": {
- "post": {
- "description": "Verifies a single credential (API key, JWT, or macaroon). Returns whether\nthe credential is active along with associated metadata. Results are cached\nfor low-latency repeated verifications; use the Cache-Control: no-cache\nheader to bypass the cache.\n\n```http\nPOST /v2/apiKeys:verify\n{\n \"credential\": \"sk_live_abc123...\"\n}\n```",
- "operationId": "VerifyAPIKey",
- "requestBody": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- },
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/v2VerifyAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- },
- "summary": "Verify API Key",
- "tags": ["SelfService"]
- }
- }
- },
- "tags": [
- {
- "description": "Administrative operations for managing static credentials (API keys, personal access tokens, and similar long-lived secrets). Deploy behind authentication and authorization. Supports issued keys (generated by Talos), imported keys (from external systems), and credential verification.",
- "name": "StaticCredentials"
- },
- {
- "description": "Self-service operations for credential holders. Allows key holders to revoke their own credentials using proof of possession.",
- "name": "SelfService"
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-get-jwks.api.mdx b/docs/talos/reference/api/admin-get-jwks.api.mdx
index c26fbd7e10..628ed39882 100644
--- a/docs/talos/reference/api/admin-get-jwks.api.mdx
+++ b/docs/talos/reference/api/admin-get-jwks.api.mdx
@@ -22,13 +22,13 @@ import Translate from "@docusaurus/Translate"
-
+
Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
```http
-GET /v2/admin/derivedKeys/jwks.json
+GET /v2/admin/.well-known/jwks.json
```
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
deleted file mode 100644
index ce0b4454cd..0000000000
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.RequestSchema.json
+++ /dev/null
@@ -1,102 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "properties": {
- "requests": {
- "items": {
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "Additional metadata (OPTIONAL)",
- "type": "object"
- },
- "name": {
- "title": "Human-readable name (REQUIRED)",
- "type": "string"
- },
- "actor_id": {
- "title": "Actor identifier (REQUIRED)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "raw_key": {
- "title": "The actual key string to import (REQUIRED)",
- "type": "string"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "Scopes for the imported key (OPTIONAL)",
- "type": "array"
- },
- "ttl": {
- "title": "Time-to-live for expiration (OPTIONAL)",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
- "type": "object"
- },
- "title": "Keys to import",
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchImportAPIKeysRequest"
- }
- }
- },
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
deleted file mode 100644
index fc166755fa..0000000000
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.StatusCodes.json
+++ /dev/null
@@ -1,189 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
- "properties": {
- "failure_count": { "format": "int32", "type": "integer" },
- "results": {
- "items": {
- "description": "BatchImportResult contains the result for one key in a batch import request.",
- "properties": {
- "error_code": {
- "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
- "enum": [
- "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
- "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
- "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
- "BATCH_IMPORT_ERROR_INTERNAL"
- ],
- "type": "string",
- "title": "v2BatchImportErrorCode"
- },
- "error_message": {
- "title": "Human-readable failure reason",
- "type": "string"
- },
- "imported_api_key": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "create_time": {
- "format": "date-time",
- "type": "string"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_hash": {
- "title": "SHA-512/256 of credential (for audit)",
- "type": "string"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": {
- "format": "date-time",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- },
- "index": {
- "format": "int32",
- "title": "Zero-based index in request.requests",
- "type": "integer"
- }
- },
- "type": "object",
- "title": "v2BatchImportResult"
- },
- "type": "array"
- },
- "success_count": { "format": "int32", "type": "integer" }
- },
- "type": "object",
- "title": "v2BatchImportAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "Batch import completed. Check per-item results for individual status."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
deleted file mode 100644
index b92bbf397c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-batch-import-api-keys.api.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-id: admin-plane-service-batch-import-api-keys
-title: "Batch Import API Keys"
-description: "Imports up to 1000 external API keys in one request. Returns per-item"
-sidebar_label: "Batch Import API Keys"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item succeeds, response is 200 OK.
-If all items fail, the endpoint returns a non-200 error.
-
-```http
-POST /v2/admin/importedApiKeys:batchImport
-{
- "requests": [
- {"raw_key": "sk_live_abc", "name": "Stripe key", "actor_id": "user_1"},
- {"raw_key": "ghp_xyz", "name": "GitHub PAT", "actor_id": "user_2"}
- ]
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
deleted file mode 100644
index 092cc31162..0000000000
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
deleted file mode 100644
index cd80ba989c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.StatusCodes.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
- "responses": {
- "200": {
- "content": { "application/json": { "schema": { "type": "object" } } },
- "description": "A successful response."
- },
- "204": {
- "content": { "application/json": { "schema": {} } },
- "description": "Imported key deleted successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
deleted file mode 100644
index a4dd8d7b5f..0000000000
--- a/docs/talos/reference/api/admin-plane-service-delete-imported-api-key.api.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: admin-plane-service-delete-imported-api-key
-title: "Delete Imported API Key"
-description: "Permanently deletes an imported key (hard delete). The key is removed from"
-sidebar_label: "Delete Imported API Key"
-hide_title: true
-hide_table_of_contents: true
-api: eJzdVcluIzcQ/ZUCT5JBS46SmUOfIsAGonGCKF4wB9sYl5vVao7ZZA9Z0kxDaCAfkS/MlwTFlsfyggS+5sS1tldVr7bKUCqjbdkGrwq1pNigJ8+uA0OOmBKgB9u0ITIZuKcORjVGs3sdT+CipnxtE0RqwoYMVDE0155rAoOMd5hoApeJ4Iw24Z7my8UpdVCFCClUPGiywcMoUhmahrwhM55c+2t/e3tbM7fX/vjk15OLE5huZlM0jfXTB4/mrT2lLk2399R9sqbPMkqr0FJE0bowqlBzkVk69HROcWNL+nSc3V88aMkuKa1ajNgQU0yquNo+A+f8l/m7H2bT2bv3UGOqIVQgMT4F5+zkj8vF2cnxWGllRapFrpVWHhtShRrcVFpF+rK2kYwqOK5Jq1TW1KAqtoq7Vn4mjtavVN/fyOfUBp8oyfvs6EiWMngmz7LFtnW2zOFOPyfxdftSX7j7TCWrvu/1s7jmkNZlSSlVawcPpiaq12p29NNbTL2ie7EPzlAzZs+c67IdQxWuHb8prDZKjtkOoJTBkKxViA2yKpT1/ONM6YforWdaURyMMVqXpSxTkzdojBU76Jb7anv9zMzPg7qXSdLPYNaKLTu5aGPgcLeu5r5Tj98wRsznhlLC1Rt1xrY8Z+R1ejWdHtaevrVUCtYUY4j7WRW1uJL6ftkW6kYc4jpI0wzZyk3BtSrUfzdfLvkqSCxPXfo9dnCBLiRhCYTarurDlmJOli8J5stFLpAGPa6oIc+QBo8msGCo0RtHKXebFA2UkQx5tujA2YrKrnRUgE1pbf1KNCUNG4q26uTMNTWADC58BYdMvuw0GIp2I6+pDpEPnRXi4nBPPsHow8cLQG/gNywxhuDHOh+j8JfIYK7fTFFCf+K+TZBaZxms5wD8NUArwKZCPh3CwUEGGzLaBwfw959/5Yi/u78f+0giIQ0xMLKsmTf1jml2vtPOWw0fPp6ejwcjx8j4xMYLqDMsu66CUbJ+5UjDHXJZa0jkqsPB2niv3B7TN18ulFYbimlI7GxyJEXchsQN5gbd8dzAr/C9/QWigWKfVMZev/9/Zs+ua5m+8bR1aL1AtI4us1bupSu1EW7K6qRpnipUWhW7OXGjVR0Si8R2K8FcRtf3cv1lTbFTxdWNVhuMFu8kUzKybJK9UUWFLtG/4D06242gMbx5sr0a4gO1eUnzBt1aTkrLzHucfP1Nr1VNaChmf4fHeVlSy3tiL7i/36emISWq7/8BAMEMUw==
-sidebar_class_name: "delete api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Permanently deletes an imported key (hard delete). The key is removed from the database. Use RevokeAPIKey for soft deletion
-(recommended).
-
-```http
-DELETE /v2/admin/importedApiKeys/{key_id}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
deleted file mode 100644
index 2118789f31..0000000000
--- a/docs/talos/reference/api/admin-plane-service-derive-token.RequestSchema.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "algorithm": {
- "default": "TOKEN_ALGORITHM_UNSPECIFIED",
- "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
- "enum": [
- "TOKEN_ALGORITHM_UNSPECIFIED",
- "TOKEN_ALGORITHM_JWT",
- "TOKEN_ALGORITHM_MACAROON"
- ],
- "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
- "type": "string"
- },
- "credential": {
- "title": "The API key secret (issued or imported) to derive a token from",
- "type": "string"
- },
- "custom_claims": { "type": "object" },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "ttl": { "type": "string" }
- },
- "title": "Token derivation messages",
- "type": "object"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
deleted file mode 100644
index 7b33c4812d..0000000000
--- a/docs/talos/reference/api/admin-plane-service-derive-token.StatusCodes.json
+++ /dev/null
@@ -1,51 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "token": {
- "properties": {
- "claims": { "type": "object" },
- "expire_time": { "format": "date-time", "type": "string" },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "token": { "type": "string" }
- },
- "title": "Token represents a short-lived derived token (JWT or Macaroon)",
- "type": "object"
- }
- },
- "type": "object",
- "title": "v2DeriveTokenResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx b/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
deleted file mode 100644
index be3ae63d56..0000000000
--- a/docs/talos/reference/api/admin-plane-service-derive-token.api.mdx
+++ /dev/null
@@ -1,46 +0,0 @@
----
-id: admin-plane-service-derive-token
-title: "Derive Token"
-description: "Mints a short-lived JWT or Macaroon token from an API key. Works with both"
-sidebar_label: "Derive Token"
-hide_title: true
-hide_table_of_contents: true
-api: eJztVs1y20YMfhXMnmwPJafujb1UtZ1ETm0rtjKeqelxIBISN17ubnZB2RyNZvoQfcI+SWeXkvVjJZ6m1+oicQUC2O8DPmAmCvK5k5al0SIV51KzBwRfGscdJadUwNnNEIyDc8zRGaOBzQNpGDtTAWroDfrwQE0Xbox78PAouYSR4TLT0vuaCkBdgKyscUxFsPRdGJYEBbnovfUmdUlOsgcuCSy5SnovjfZgxuEo0xYdaX6OlulMf/78uWS2mR5cXg/hcHp0iEUl9SFa+YEan7YRMj3LNEAmckcFaZaoMpFCJqg5K0fvcnkpz97+cXo1/Hjd73a7mUhac+aF3U9lJjI9j/FEIowlhwGtfiFS0QsRBwo1XZObypzuT2LUYbiVSISjrzV5/s0UjUhnIjeaSXP4idYqmUdPh198AH8mfF5SheGXdSEOS/LRVk2Mk1xW4aGgMdaKRSqGlx9OL+57v7+7vOoP35/ff7q4Hpwe99/2T09EskVsB7atz26GaeQ2UnZanFz3YM+TGndClig1FQl4OdFU7GcaXjo47x33ri4vL9JVaURX7897xy895Tgl5M4IPRX7IhGk60qkt69cYkfSO06XmYi7RLBkRQGcwEBvCRx4S7kcS2orLHeNZTNxaEuZwzO8UHsqYGzcZnX6TF8YpnRZfR72nDG8+HMf0BGgesTGg7H4taZfgEvpIVwRpAejVRO9btYGNzYk6tlJPRHzZK1CA8/PFylpGRg85Y4Y9hatZdxzZ+0Dm0XWgGstujNO7dlU97lCWcX6WliY0RfKOVj43Ni29CTThs3Ky+IAncMmPrPaYTffYqTNMZY9VOQ9TsivclxmEF4LrSMdFSJlV1MinjrGyYnUqAbosLrAKrwxCp0Vrb012rdJH7158x+6LYL38vg7cNGTlY7uWYaUZmJsXIWhQQtk6sTTHSz8EMbL1F5D2ZF15OmlmG/K7t6Wtu/voGL7ZBVqerRW0FcLAlryNsWnB77Oc/J+XCtYMtUV0W4hZj/MVm6KTdCl5p+PVveQmmlCrg3GKNUm5FgUMsRBNVh3O0+2wvzautuJ/Dfgsc6wGdXjnm52cbmo/n/n09n8mpFrvxNmDbWmJ0t5GLXknHHraAe3OPFBdF+MraCcFXFpwlCzxoeYFrkUqfjWYBWJCNxcrSbc6RNWVtHWxHpF4ddFb4nAS4la65fbpdXdQnPW+kXqsWln5Doul66BISrjgxgjlHJSdiy5WDE6X6lrhRonVIU9w7ewdKHPUKIu1GJwjGulYJUyKDmmvMkVpRA0WepJHBAJTMnJcROeuaQKkEGZR1DIpPMmadsw/Lvem+08aZsybE3PXZnER0dT8xDewdhLcQdaDgfpwVslGaRmA/xowAZ2fRqMOnBwEBmHSPnBAfz951/xxs/pr9+9nS4JOMPI4TvEpWQxapLllGmzTeDs5sP1fhvkBBk3YryAOsKyaG3Y81JPFCUwQs7LBOLK0EbbX6v5FX29QV8kYkrOt8Qedd8E1kO9VhhVQrdTodUlWE7ajXJYU5r/191X192FEDE98aFVKHUAvHZx1LcCcSumQW5jMuF7UyTuElEGOUlvxWwWlr9PTs3n4fhrTa4R6e1dIqboJI4C2bd380SUhAU5kd7OxAM1IhXHLWGdYUgmmKs6Sun2mJgnyzd6eU6Wv2u7rngBUpG0y0Q6E1WcKcLhY1jh8VGkIm7+4e04DeLZTCjUkzpquGh9hs8/obybiA==
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys. The derived token inherits
-the permissions of the parent API key.
-
-```http
-POST /v2/admin/apiKeys:derive
-{
- "credential": "eyJhbGciOiJFZERTQSI...",
- "ttl": "1h"
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
deleted file mode 100644
index 092cc31162..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
deleted file mode 100644
index 14e67f1c0a..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.StatusCodes.json
+++ /dev/null
@@ -1,129 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_hash": {
- "title": "SHA-512/256 of credential (for audit)",
- "type": "string"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
deleted file mode 100644
index 88cfff5cfe..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-imported-api-key.api.mdx
+++ /dev/null
@@ -1,41 +0,0 @@
----
-id: admin-plane-service-get-imported-api-key
-title: "Get Imported API Key"
-description: "Retrieves details about a specific imported key. Returns metadata about"
-sidebar_label: "Get Imported API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "get api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Retrieves details about a specific imported key. Returns metadata about the imported key. The original raw key is never returned.
-
-```http
-GET /v2/admin/importedApiKeys/{key_id}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
deleted file mode 100644
index b19b7ceb16..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
deleted file mode 100644
index 9e8b47c392..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.StatusCodes.json
+++ /dev/null
@@ -1,122 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
deleted file mode 100644
index d3bba69188..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-issued-api-key.api.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: admin-plane-service-get-issued-api-key
-title: "Get Issued API Key"
-description: "Retrieves details about a specific issued API key including its status,"
-sidebar_label: "Get Issued API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "get api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Retrieves details about a specific issued API key including its status, scopes, expiration, and usage statistics. The secret is
-never returned.
-
-```http
-GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
deleted file mode 100644
index 07c363956d..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.StatusCodes.json
+++ /dev/null
@@ -1,42 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "jwks": { "title": "JSON Web Key Set", "type": "object" }
- },
- "type": "object",
- "title": "v2GetJWKSResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx b/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
deleted file mode 100644
index b15e7f1d19..0000000000
--- a/docs/talos/reference/api/admin-plane-service-get-jwks.api.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: admin-plane-service-get-jwks
-title: "Get JWKS"
-description: "Returns the JSON Web Key Set for token verification. Provides the public"
-sidebar_label: "Get JWKS"
-hide_title: true
-hide_table_of_contents: true
-api: eJztVc1u3EYMfhViTrYx3nXdNgF0qtEmhh20WdgOfPAaNXdErcY7mlFnKG2ExQJ9iD5hn6TgaBOvnaJF0GtP8yOS30cO+WmjSkom2pZt8KpQV8Rd9Am4Jri8fv8L3NIC3tEA18RQhQgcVuShp2gra1C8JjCLobcljV5tt3DWzP2KhgSeqKQSOIweA1ze3owhEtiUOiphMQDXNkGi2FtDE0FLgJHABSypnPsqhgZM8JVddjFDwkFlHRXTqYaauU15FyIsMNGr74rpFD5cXaTDCbwNzoV1Jjb3l7fvriEx+hJjCQdXb3+E199/8/pwMvdz//DwIKHm/vzNDUz70ymWjfXTyZqcO175sPbTx/UqTR5TGK2VVqGlkc9FqQp1Jg4zh56ux1R+PScWTKVVpNQGnyipYqNOT05kMcEzeZYttq3bVXMqAHKXTE0Nyq6NAsR29BYWsrJlR6pQL19JacVDK1/C4pEMq+325Y3+7Nyf7jhe7QiqrZg/74kzSJ0xlFLVOfiUyURluwo7x/8hGxNKkrUKsUFWhbKevz19ysF6piXFEYzRuuxlmZq8wbK0goNuth92q1/A/DCG23wKmzhav/zH0rQxcFh01Zkf1JMZxoj53FBKuPzKmLE114zcpb8ts4fO08eWDFMJFGOI+9WWsLhMqrj7stPUvRDiOkgfLnMPtMi1KtS/dLLSyvoqSBbPybyPA9ygCzKmgFDbZX3cUszP5A3B2ewCVjRAgx6X1JDnpwG+YKjRl24nCFXnHJhIJXm26MDZisxgHBVZAqxfSqSkdxIhZ66pAWRwYQ0OmbwZNJQUbS9fUx0iHzvbZ2XJWnIguoK+hJ/RYAzBH+p8jNSHlfhgbuA86Tf1SF80p3WWwXoOwOsArZQ0FWJ0DEdHucyQ63x0BH/+/kfO+DP9/dwPsphpiIGRZRVc0mCbNkTecacdWw0ycYcjyE/I+Azji1Lvay0cJOuXjjQskE2tIZGrjke0w71Ge3q+s9mF0qqnmMaHPZ2cSPu2IXGDeTQ9NuJyTgw7tXrWCnuj/f/f4Wv+DjsRYPrI09ah9VL3Lrosgnk671QvUpdjKa32oimtnmb0Xqs6JBb7zUaS+BDddivXv3UUB1Xc3WvVY7S4kMe/u99qVROWFFVxt1ErGkRdjKFWhKFH12Ule6nS230ROX9zo7bbvwAzNNEW
-sidebar_class_name: "get api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
-Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
-
-```http
-GET /v2/admin/derivedKeys/jwks.json
-```
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
deleted file mode 100644
index edad31b034..0000000000
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.RequestSchema.json
+++ /dev/null
@@ -1,91 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "Additional metadata (OPTIONAL)",
- "type": "object"
- },
- "name": {
- "title": "Human-readable name (REQUIRED)",
- "type": "string"
- },
- "actor_id": {
- "title": "Actor identifier (REQUIRED)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "raw_key": {
- "title": "The actual key string to import (REQUIRED)",
- "type": "string"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "Scopes for the imported key (OPTIONAL)",
- "type": "array"
- },
- "ttl": {
- "title": "Time-to-live for expiration (OPTIONAL)",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
- "type": "object"
- }
- }
- },
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
deleted file mode 100644
index a9bca0b5a4..0000000000
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.StatusCodes.json
+++ /dev/null
@@ -1,139 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "imported_api_key": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_hash": {
- "title": "SHA-512/256 of credential (for audit)",
- "type": "string"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- }
- },
- "type": "object",
- "title": "v2ImportAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key imported successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
deleted file mode 100644
index dca48e4309..0000000000
--- a/docs/talos/reference/api/admin-plane-service-import-api-key.api.mdx
+++ /dev/null
@@ -1,47 +0,0 @@
----
-id: admin-plane-service-import-api-key
-title: "Import API Key"
-description: "Imports an external API key into the system. Allows importing keys from"
-sidebar_label: "Import API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is
-hashed and stored securely (HMAC). Imported keys support token derivation (JWT/Macaroon) like issued keys.
-
-```http
-POST /v2/admin/importedApiKeys
-{
- "raw_key": "sk_live_abc123xyz",
- "name": "Imported Stripe Key",
- "actor_id": "user_123"
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
deleted file mode 100644
index 77bac93458..0000000000
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.RequestSchema.json
+++ /dev/null
@@ -1,69 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "ttl": { "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssueAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
deleted file mode 100644
index 2bb07c09e5..0000000000
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.StatusCodes.json
+++ /dev/null
@@ -1,136 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "secret": {
- "title": "Only returned on creation",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2IssueAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key issued successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
deleted file mode 100644
index eddb832fa8..0000000000
--- a/docs/talos/reference/api/admin-plane-service-issue-api-key.api.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-id: admin-plane-service-issue-api-key
-title: "Issue API Key"
-description: "Creates a new API key for a given actor. The secret is returned only once"
-sidebar_label: "Issue API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Creates a new API key for a given actor. The secret is returned only once in the response and cannot be retrieved later. Keys can
-be scoped with specific permissions and have optional expiration.
-
-```http
-POST /v2/admin/issuedApiKeys
-{
- "name": "production-service",
- "actor_id": "user_123",
- "scopes": ["read", "write"],
- "ttl": "8760h"
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
deleted file mode 100644
index 76d4d28b3c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.ParamsDetails.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": { "format": "int32", "type": "integer" }
- },
- {
- "description": "Cursor token for pagination (OPTIONAL)",
- "in": "query",
- "name": "page_token",
- "schema": { "type": "string" }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
deleted file mode 100644
index e182533c49..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.StatusCodes.json
+++ /dev/null
@@ -1,149 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "imported_api_keys": {
- "items": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_hash": {
- "title": "SHA-512/256 of credential (for audit)",
- "type": "string"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- },
- "title": "List of imported keys",
- "type": "array"
- },
- "next_page_token": {
- "title": "Token for fetching the next page (empty if no more results)",
- "type": "string"
- }
- },
- "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
- "type": "object"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
deleted file mode 100644
index 265ce18dcc..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-imported-api-keys.api.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: admin-plane-service-list-imported-api-keys
-title: "List Imported API Keys"
-description: "Lists all imported keys with filtering. Returns imported keys only (not"
-sidebar_label: "List Imported API Keys"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "get api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports pagination and AIP-160 filter
-expressions.
-
-```http
-GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
deleted file mode 100644
index 4a5e5fb847..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.ParamsDetails.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": { "format": "int32", "type": "integer" }
- },
- {
- "description": "Cursor token for pagination",
- "in": "query",
- "name": "page_token",
- "schema": { "type": "string" }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
deleted file mode 100644
index e9fcb6db7c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.RequestSchema.json
+++ /dev/null
@@ -1 +0,0 @@
-{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
deleted file mode 100644
index 5cabad53f6..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.StatusCodes.json
+++ /dev/null
@@ -1,138 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_keys": {
- "items": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "type": "array"
- },
- "next_page_token": { "type": "string" }
- },
- "type": "object",
- "title": "v2ListIssuedAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
deleted file mode 100644
index 50dd84f74d..0000000000
--- a/docs/talos/reference/api/admin-plane-service-list-issued-api-keys.api.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: admin-plane-service-list-issued-api-keys
-title: "List Issued API Keys"
-description: "Lists issued API keys with optional filtering. Supports cursor-based"
-sidebar_label: "List Issued API Keys"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "get api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter expressions. Returns only
-issued (generated) API keys; use ListImportedAPIKeys for imported keys.
-
-```http
-GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
deleted file mode 100644
index b19b7ceb16..0000000000
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
deleted file mode 100644
index fb84fc671f..0000000000
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.RequestSchema.json
+++ /dev/null
@@ -1,34 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "reason_text": {
- "title": "Only allowed when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- }
- },
- "type": "object",
- "title": "AdminPlaneServiceRevokeAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
deleted file mode 100644
index d3cec6dad6..0000000000
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.StatusCodes.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
- "responses": {
- "200": {
- "content": { "application/json": { "schema": { "type": "object" } } },
- "description": "A successful response."
- },
- "204": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key revoked successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
deleted file mode 100644
index 0d0a4c219f..0000000000
--- a/docs/talos/reference/api/admin-plane-service-revoke-api-key.api.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
----
-id: admin-plane-service-revoke-api-key
-title: "Revoke API Key"
-description: "Immediately revokes an API key (issued or imported). Once revoked, the key"
-sidebar_label: "Revoke API Key"
-hide_title: true
-hide_table_of_contents: true
-api: eJydVu1O4zgUfZUr/xpQWtjurjSbX9uBMgQGWtryMTMZFTe5bTw4dta+KUQo0j7EPuE+ycpOKYWCEPujSpze3ON7zznXuWcp2sSIgoRWLGRRnmMqOKGswOBC36AFrqA7iOAGK/ggrC0xBW1A5IU2hOlWG/oqwWV0GgBl6GJjlXAFSoPUao4GpgilxRRm2gAvKUNFIuEOtg3jTFjQBRq/BmFBGIMLNFZMJbZjNWySu7wWuHFoxIVapUsFQVGaQlu07VjF6vr6OiMqYjXoj8aws+js8DQXaocX4hgru7P7y+HZt6s/Lr6eHR99+nh19u2s+V2dhU0hsbqPFUDMDHKrVcxCiNmwd9Hf646j/ulk2OuO+qeT497XyV7/ZDDsn0SjXsxiVXtwFrBVPVHKQtZ18APJFY7QLESCk6am7iA6xooFrOCG50hoLAu/3zPh2Cg4ZSxgiufIQnaD1USkLGAG/yqFwZSFZEoMmE0yzDkL7xlVhYu0ZISas7r+0QSjpU86rVxEohWhInfLi0IuKdj5aR3992upCuMKIIHWrZouuLsUZ7yUxMIXunF+Ohr09qKDqLfPgmfKcuU2YEOfCwqjFyJFC5ZMmVBpMPUiaoKgQbQglC1csTCtYHiwB793Pu62Y3XutCQUTDVl4LkFrlKwKGettSwzqW8bRUALNjc8GEYX0Zfe597kMhof7g+7l6cheKpaWskqBKUJuJT6tkF7lp4FDFWZs/D7m814SzovhnQPDqIvUfNo77B7+vmVVKPzQW846u2/8vcLVbIfwTOxBIwESfdg0XnOFauDpQImhHdePA/BfSWrVYduM3wgzpn4JdznsHW9eqKnPzGhtY1seGbdMl7QdV1v2uGupY2YC8XlwHnqtHHP1Me7aFtoZRtZd3Z332WKpzv16E9V3gVbJglaOyslPEC1HW5n97f3QL2UezmEl5N2DUlWHmJlzf9t80Sn6K4zbXLuPC4U/dp5JE0owjmaBoy4kP4tQZj7G56mwuFwOVhPWwfPYP5s0m3Oq9e1UBhNelrOusqzuAzjxnC/ztFaPn9nTlMkI+JU2heZVFAqvCswIUwBjdFmnVCXls/drN6UqTNXjpRpN/gLbcmPd8pYyDZPovtmrNfLc4cFzJE0fJzavTueFxLXp/Cb0+aJWVetCJhQM90M8fVS+6aCMZfaOtNyyMQ8axVovAjc0f4gvJwrPsccFYFtKm1DRJBxlUq0/uB3YoTEYOqOdy5BihkmVSIxBPfpINTcn+EBLNCIWeXWlGEOnEDqW5CcUCVVACkasXD/2kwbakmxwBRI36Cy8OHocuyH/QlPuNFabQV+6Rvo3uHeF37qj7Nm+8KCLaQgEIo00K2GwhFmQxfUgu1tTyJ4Fre34d+///EVr7a/XnvzERSA0cTJXT1xwfKLaLl3XO42gKPL49FWA7LPiT/B2Gi1b8vSrfDBCjWXGMCUU5IFj6fPDW6tyfiRvu4gYgHz302e2E57l9X1f7HVasI=
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for authentication. This
-operation is irreversible. Revoked keys are retained for audit purposes.
-
-```http
-POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
-{
- "reason": "REVOCATION_REASON_KEY_COMPROMISE"
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
deleted file mode 100644
index f832c1b781..0000000000
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "parameters": [
- {
- "description": "key_id is the ID of the existing API key to rotate",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
deleted file mode 100644
index ccf8f9b6f6..0000000000
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.RequestSchema.json
+++ /dev/null
@@ -1,77 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "metadata for the new API key (inherits from old key if not provided)",
- "type": "object"
- },
- "name": {
- "title": "name for the new API key (inherits from old key if not provided)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "scopes for the new API key (inherits from old key if not provided)",
- "type": "array"
- },
- "update_mask": {
- "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "AdminPlaneServiceRotateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
deleted file mode 100644
index e7c5a62898..0000000000
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.StatusCodes.json
+++ /dev/null
@@ -1,223 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "old_issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "secret": {
- "title": "secret is the new API key secret (only returned once, never retrievable again)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RotateIssuedAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key rotated successfully. New key issued, old key revoked."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
deleted file mode 100644
index 6a0604cc19..0000000000
--- a/docs/talos/reference/api/admin-plane-service-rotate-issued-api-key.api.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-id: admin-plane-service-rotate-issued-api-key
-title: "Rotate Issued API Key"
-description: "Generates a new secret for an issued API key. Creates a new API key with a"
-sidebar_label: "Rotate Issued API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret, and immediately revokes the old
-key. This is the recommended way to update scopes, metadata, or rotate credentials.
-
-For zero-downtime rotation, use this workflow instead:
-
-1. IssueAPIKey with new credentials
-2. Deploy new secret to all services
-3. Verify new secret works everywhere
-4. RevokeAPIKey to remove the old key
-
-```http
-POST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
-{
- "scopes": ["read"]
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
deleted file mode 100644
index b19b7ceb16..0000000000
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.ParamsDetails.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
deleted file mode 100644
index 034305392d..0000000000
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.RequestSchema.json
+++ /dev/null
@@ -1,53 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "update_mask": { "type": "string" }
- },
- "type": "object",
- "title": "AdminPlaneServiceUpdateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
deleted file mode 100644
index 9e8b47c392..0000000000
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.StatusCodes.json
+++ /dev/null
@@ -1,122 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "revocation_reason_text": {
- "title": "Only set when reason is PRIVILEGE_WITHDRAWN",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
deleted file mode 100644
index 640939875c..0000000000
--- a/docs/talos/reference/api/admin-plane-service-update-issued-api-key.api.mdx
+++ /dev/null
@@ -1,46 +0,0 @@
----
-id: admin-plane-service-update-issued-api-key
-title: "Update Issued API Key"
-description: "Updates metadata, scopes, or rate limits of an issued key without rotating"
-sidebar_label: "Update Issued API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "patch api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedAPIKey to change the
-secret.
-
-```http
-PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
-{
- "scopes": ["read"],
- "update_mask": {"paths": ["scopes"]}
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/batch-verify-api-keys.api.mdx b/docs/talos/reference/api/batch-verify-api-keys.api.mdx
new file mode 100644
index 0000000000..b5aacf33b1
--- /dev/null
+++ b/docs/talos/reference/api/batch-verify-api-keys.api.mdx
@@ -0,0 +1,45 @@
+---
+id: batch-verify-api-keys
+title: "Batch Verify API Keys"
+description: "Verifies multiple credentials in a single request. Efficiently verifies up"
+sidebar_label: "Batch Verify API Keys"
+hide_title: true
+hide_table_of_contents: true
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
+verified independently; partial failures are returned in the response.
+
+```http
+POST /v2/apiKeys:batchVerify
+{
+ "requests": [
+ {"credential": "sk_live_abc123..."},
+ {"credential": "sk_live_xyz789..."}
+ ]
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
deleted file mode 100644
index aaea5e239f..0000000000
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.RequestSchema.json
+++ /dev/null
@@ -1,30 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "requests": {
- "items": {
- "properties": {
- "credential": {
- "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyRequest"
- },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchVerifyAPIKeysRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
deleted file mode 100644
index 3f2a6537e5..0000000000
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.StatusCodes.json
+++ /dev/null
@@ -1,121 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "results": {
- "items": {
- "properties": {
- "error_code": {
- "default": "VERIFICATION_ERROR_UNSPECIFIED",
- "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
- "enum": [
- "VERIFICATION_ERROR_UNSPECIFIED",
- "VERIFICATION_ERROR_INVALID_FORMAT",
- "VERIFICATION_ERROR_EXPIRED",
- "VERIFICATION_ERROR_REVOKED",
- "VERIFICATION_ERROR_NOT_FOUND",
- "VERIFICATION_ERROR_SIGNATURE_INVALID",
- "VERIFICATION_ERROR_INTERNAL",
- "VERIFICATION_ERROR_IP_NOT_ALLOWED",
- "VERIFICATION_ERROR_RATE_LIMITED"
- ],
- "title": "VerificationErrorCode provides type-safe error codes for verification failures",
- "type": "string"
- },
- "error_message": {
- "title": "Human-readable error message (only set if is_active=false)",
- "type": "string"
- },
- "expire_time": { "format": "date-time", "type": "string" },
- "is_active": { "type": "boolean" },
- "key_id": { "type": "string" },
- "metadata": { "type": "object" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "rate_limit_remaining": {
- "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
- "format": "int64",
- "type": "string"
- },
- "rate_limit_reset_time": {
- "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
- "format": "date-time",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyResponse"
- },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchVerifyAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
deleted file mode 100644
index 59806b1c07..0000000000
--- a/docs/talos/reference/api/data-plane-service-batch-verify-api-keys.api.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-id: data-plane-service-batch-verify-api-keys
-title: "Batch Verify API Keys"
-description: "Verifies multiple credentials in a single request. Efficiently verifies up"
-sidebar_label: "Batch Verify API Keys"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
-verified independently; partial failures are returned.
-
-```http
-POST /v2/admin/apiKeys:batchVerify
-{
- "requests": [
- {"credential": "sk_live_abc123..."},
- {"credential": "eyJhbGciOiJFZERTQSI..."}
- ]
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
deleted file mode 100644
index 5f67130aa1..0000000000
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.RequestSchema.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "properties": {
- "credential": {
- "title": "Full API key secret or imported key (REQUIRED)",
- "type": "string"
- },
- "reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- }
- },
- "type": "object",
- "title": "v2SelfRevokeAPIKeyRequest"
- }
- }
- },
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
deleted file mode 100644
index 506ca96823..0000000000
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.StatusCodes.json
+++ /dev/null
@@ -1,40 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
- "type": "object",
- "title": "v2SelfRevokeAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
deleted file mode 100644
index bdd4dff906..0000000000
--- a/docs/talos/reference/api/data-plane-service-self-revoke-api-key.api.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-id: data-plane-service-self-revoke-api-key
-title: "Self-Revoke API Key"
-description: "Allows an API key holder to revoke their own key. The caller must provide"
-sidebar_label: "Self-Revoke API Key"
-hide_title: true
-hide_table_of_contents: true
-api: eJztV19v2zYQ/yqHe0oC2clSDBj0NC9xWjdt7NlJgyEKUlo6W2woUiMpJ4JhYB9in3CfZDjKsR3XbRBgD8Mwv1gij8f787vfneaYkUutLL00GmPsKGUeHAgNnUEP7qmG3KiMLHgDlmbmnsDnJC2YB83bbbjMCVKhFFkoKuehtGYmM0q0zwkmlVIrTY5SSx6EYxkzATOB0jhHzkmj2zCqytJY70A6V1H2dMwlWugMZMGblIWlNry/vgReLkQqrDEavLkn7SAVWhsPYwJHatJqTM5gz+dUJ1pYAueFJ0XO7bcTnWg2fzDsfep96L7t3l33Lt+dDjvXF2BJOKNBOmB9gsNCGUyMXStOBQct0XsiK6RuGa3qRufnz59z78tED/qjSzicHR+KUp5T7WI+Oww2JXqeaIAEU0sZaS+FSjCGBN39nZIzuhPj9IfjN+12O8GokWxMaqSG3U/9k85lr39xN+x2Rv2Lu/Pub3cn/Y+DYf9jb9RNMNGLYAlGaEqywdZehjGeCi8GSmgakZ3JlO5GK6M6g9451Rihpd8rcv4Xk9UYzzE12pP2/CjKUsnG88MvjjEzR5fmVAh+eg6mbcXDRmsTzVeALNHjeokrqaewAtbLoMIIS8vue0kueLKKNr956RVhjGc7YGrsM8zB3rD761Vv2D3dxwh9XfI5563UU1xEy9w0IZiISnmMd+To6mI06J70znrdU4y2gjVcIWrYQG9ZSA6ct1XqK0sZrGG3BKgDqV0peW9cw/DsBH48/umonegrRxlIDWPjcwgADfWyBV6YcCYCaKEFXxu8ozJi6KzgHj8rDqm31WOEpKsC45sXg/ESoHeKdM7Oeh96zdLJu87F22+oGl0NusNR9/Qb2zu8xNvtJEcrtMyOt3OFi8VK3Iy/UOqfiX+jDnDBx/6FJcPVz5DC2NuKInxsGSunUgs1EFYUF6Jgv8ZMDgH6rjTaNfV1fHT0jxJGo5pp2JKvrKYMjAZXpSk5N6nUNuIClLtF6esNOXxdcpo7d2Wns3nzk99tDHLLqn+F71vMZDLi/4mxhWD6kNq/OV6bLrWnKdnmMi+kCqekpyI8iCyTfI9Qg021i20C/LlRN9+msO8AuLTGm3E16eiQ76WYsFaE94KcE9NX6rRlOvLCV25nmDVUmh5LSpl8yVpjN6PNasXUMats9zIu24J8brjRlcbxlaXwOca4uw1jhJyY4brfdR9FUSrabhZrGnii+hcobRGh1BPzNcj7toZLoQwPOiAgl9O8VZINedcprQq8EFpMqSDtwTXetaHnIRc6U+TWJb22EpScUFqniuIwRHHl87gUwYysnNRLJihAeFDmAZTwpNM6goysnPGuy431LZ4/sqeJau9p1Pq4HLX2o/AaWIfPiFARq2GKzZcOXKmkB6m9Af9goOQkuZiFWnBwEFoIhMwdHMBff/wZPF6Zv+n7XhgHI7CGB7doyXbRsjkvbaeltRG8vz4f7TeXMDie3fFVqENYlgUKe07qqaIIxsKnebQ5QO5vIHedvs6ghxHOyLomscftI846w64QodZ1w5RMMa0GbyE8zYz1DBUbtPH/DP5fnMGXROjp0R+WSkjNUKlsGEMbhrrBGdP9Do66jTBnLotvcD4fC0dXVi0WvPx7RbbG+OY2wpmwUowZoje3iwhzEhlZjG/meE81xnjS4Kt1yYawuKoCjW+3qEX0dKKTplT678pu0i0HGqNmLIjnWIR+hlY8MGeKB4wxfIrw6dCJwtocldDTKvQPbHTy72/N4RAd
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Allows an API key holder to revoke their own key. The caller must provide the full API key secret as proof of possession. Supports
-issued API keys and imported keys. JWT and macaroon tokens cannot be self-revoked (they are stateless).
-
-The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
-
-```http
-POST /v2/apiKeys:selfRevoke
-{
- "credential": "sk_live_abc123...",
- "reason": "REVOCATION_REASON_KEY_COMPROMISE"
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json b/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
deleted file mode 100644
index b4df248475..0000000000
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.RequestSchema.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "credential": {
- "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json b/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
deleted file mode 100644
index c7b7c2c7b6..0000000000
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.StatusCodes.json
+++ /dev/null
@@ -1,109 +0,0 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "error_code": {
- "default": "VERIFICATION_ERROR_UNSPECIFIED",
- "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
- "enum": [
- "VERIFICATION_ERROR_UNSPECIFIED",
- "VERIFICATION_ERROR_INVALID_FORMAT",
- "VERIFICATION_ERROR_EXPIRED",
- "VERIFICATION_ERROR_REVOKED",
- "VERIFICATION_ERROR_NOT_FOUND",
- "VERIFICATION_ERROR_SIGNATURE_INVALID",
- "VERIFICATION_ERROR_INTERNAL",
- "VERIFICATION_ERROR_IP_NOT_ALLOWED",
- "VERIFICATION_ERROR_RATE_LIMITED"
- ],
- "title": "VerificationErrorCode provides type-safe error codes for verification failures",
- "type": "string"
- },
- "error_message": {
- "title": "Human-readable error message (only set if is_active=false)",
- "type": "string"
- },
- "expire_time": { "format": "date-time", "type": "string" },
- "is_active": { "type": "boolean" },
- "key_id": { "type": "string" },
- "metadata": { "type": "object" },
- "actor_id": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "rate_limit_remaining": {
- "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
- "format": "int64",
- "type": "string"
- },
- "rate_limit_reset_time": {
- "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
- "format": "date-time",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
diff --git a/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx b/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
deleted file mode 100644
index 48e4e387f7..0000000000
--- a/docs/talos/reference/api/data-plane-service-verify-api-key.api.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-id: data-plane-service-verify-api-key
-title: "Verify API Key"
-description: "Verifies a single API key or derived token. Validates the credential's"
-sidebar_label: "Verify API Key"
-hide_title: true
-hide_table_of_contents: true
-api: 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
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with
-any credential type (issued keys, imported keys, JWT, macaroon). The verification logic automatically detects the credential type.
-
-Returns verification result with claims and metadata. Heavily cached for optimal performance (typically <1ms).
-
-Cache Control (HTTP Headers):
-
-- Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
-- Cache-Control: no-store - Bypasses cache read AND write (never cached)
-- Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
-
-Use cache bypass after revoking keys when immediate verification is critical.
-
-```http
-POST /v2/admin/apiKeys:verify
-{
- "credential": "sk_live_abc123..."
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
index 75fcaa9cef..d29e1bf998 100644
--- a/docs/talos/reference/api/ory-talos-api.info.mdx
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -25,12 +25,12 @@ verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), a
The API is split into two services:
- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification
-- **SelfService** — self-service revocation for credential holders
+- **SelfService** — self-service verification, batch verification, and revocation for credential holders
### Quick Links
- [**Admin Plane**](./admin-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
-- [**Data Plane**](./admin-verify-api-key) — High-performance verification (single, batch, self-revoke)
+- [**Data Plane**](./verify-api-key) — High-performance verification (single, batch, self-revoke)
```mdx-code-block
import DocCardList from '@theme/DocCardList';
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
index e688743952..80b2017240 100644
--- a/docs/talos/reference/api/sidebar.ts
+++ b/docs/talos/reference/api/sidebar.ts
@@ -112,6 +112,18 @@ const sidebar: SidebarsConfig = {
type: "category",
label: "SelfService",
items: [
+ {
+ type: "doc",
+ id: "reference/api/batch-verify-api-keys",
+ label: "Batch Verify API Keys",
+ className: "api-method post",
+ },
+ {
+ type: "doc",
+ id: "reference/api/verify-api-key",
+ label: "Verify API Key",
+ className: "api-method post",
+ },
{
type: "doc",
id: "reference/api/revoke-api-key",
diff --git a/docs/talos/reference/api/verify-api-key.api.mdx b/docs/talos/reference/api/verify-api-key.api.mdx
new file mode 100644
index 0000000000..f9a6f876b4
--- /dev/null
+++ b/docs/talos/reference/api/verify-api-key.api.mdx
@@ -0,0 +1,42 @@
+---
+id: verify-api-key
+title: "Verify API Key"
+description: "Verifies a single credential (API key, JWT, or macaroon). Returns whether"
+sidebar_label: "Verify API Key"
+hide_title: true
+hide_table_of_contents: true
+sidebar_class_name: "post api-method"
+info_path: reference/api/ory-talos-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
+
+
+
+Verifies a single credential (API key, JWT, or macaroon). Returns whether the credential is active along with associated metadata.
+Results are cached for low-latency repeated verifications; use the `Cache-Control: no-cache` header to bypass the cache.
+
+```http
+POST /v2/apiKeys:verify
+{
+ "credential": "sk_live_abc123..."
+}
+```
+
+
+ Request
+
+
+
+
+
+
+
From 278c04cca4031acba21bc72a8970c386909452e9 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Tue, 28 Apr 2026 11:25:09 +0200
Subject: [PATCH 7/8] chore: synchronize workspaces
---
docs/talos/CLAUDE.md | 34 +--
docs/talos/concepts/architecture.md | 73 +++---
docs/talos/concepts/caching.md | 18 +-
docs/talos/concepts/credential-types.md | 26 +-
docs/talos/concepts/index.md | 3 +-
docs/talos/concepts/ip-restrictions.md | 73 +++---
docs/talos/concepts/rate-limiting.md | 86 ++++---
docs/talos/concepts/security-model.md | 121 ++++++----
.../concepts/token-derivation-security.md | 66 ++++--
docs/talos/concepts/token-format.md | 7 +-
docs/talos/index.md | 37 +--
docs/talos/integrate/batch-operations.md | 30 +--
docs/talos/integrate/derive-tokens.md | 69 ++++--
docs/talos/integrate/error-handling.md | 85 ++++---
docs/talos/integrate/import-keys.md | 50 ++--
docs/talos/integrate/index.md | 78 ++++--
docs/talos/integrate/ip-restrictions.md | 50 ++--
docs/talos/integrate/issue-and-verify.md | 60 ++---
docs/talos/integrate/key-lifecycle.md | 54 +++--
docs/talos/integrate/rate-limiting.md | 83 ++++---
docs/talos/integrate/sdk/curl.md | 42 ++--
docs/talos/integrate/sdk/go.md | 81 +++++--
docs/talos/integrate/self-revocation.md | 46 ++--
docs/talos/operate/benchmarks.md | 31 +--
docs/talos/operate/cache/index.md | 8 +-
docs/talos/operate/cache/memory.md | 8 +-
docs/talos/operate/cache/redis.md | 73 +++++-
docs/talos/operate/configure.md | 42 +++-
docs/talos/operate/database/cockroachdb.md | 36 ++-
docs/talos/operate/database/index.md | 3 +-
docs/talos/operate/database/migrations.md | 48 +++-
docs/talos/operate/database/mysql.md | 40 ++--
docs/talos/operate/database/postgresql.md | 60 +++--
docs/talos/operate/deploy/edge-proxy.md | 63 +++--
docs/talos/operate/deploy/kubernetes.md | 19 +-
docs/talos/operate/deploy/separate-planes.md | 49 +++-
docs/talos/operate/index.md | 26 +-
docs/talos/operate/install.md | 5 +-
.../talos/operate/monitoring/health-checks.md | 4 +-
docs/talos/operate/monitoring/index.md | 3 +-
docs/talos/operate/monitoring/metrics.md | 2 +-
docs/talos/operate/monitoring/tracing.md | 5 +-
docs/talos/operate/multi-tenancy.md | 124 +++++++++-
docs/talos/operate/secrets.md | 110 +++++++--
docs/talos/operate/security-hardening.md | 56 ++++-
docs/talos/operate/tls.md | 3 +-
docs/talos/operate/troubleshooting.md | 12 +-
docs/talos/quickstart/docker-commercial.md | 7 +-
docs/talos/quickstart/index.md | 30 +--
docs/talos/quickstart/preview.mdx | 47 ++--
...n-batch-import-api-keys.RequestSchema.json | 103 +-------
...min-batch-import-api-keys.StatusCodes.json | 186 +--------------
.../api/admin-batch-import-api-keys.api.mdx | 69 ++++--
...n-batch-verify-api-keys.RequestSchema.json | 31 +--
...min-batch-verify-api-keys.StatusCodes.json | 126 +---------
.../api/admin-batch-verify-api-keys.api.mdx | 69 ++++--
...delete-imported-api-key.ParamsDetails.json | 12 +-
...delete-imported-api-key.RequestSchema.json | 2 +-
...n-delete-imported-api-key.StatusCodes.json | 37 +--
.../api/admin-delete-imported-api-key.api.mdx | 68 ++++--
.../api/admin-derive-token.RequestSchema.json | 39 +--
.../api/admin-derive-token.StatusCodes.json | 52 +---
.../reference/api/admin-derive-token.api.mdx | 69 ++++--
...in-get-imported-api-key.ParamsDetails.json | 12 +-
...in-get-imported-api-key.RequestSchema.json | 2 +-
...dmin-get-imported-api-key.StatusCodes.json | 126 +---------
.../api/admin-get-imported-api-key.api.mdx | 67 ++++--
...dmin-get-issued-api-key.ParamsDetails.json | 11 +-
...dmin-get-issued-api-key.RequestSchema.json | 2 +-
.../admin-get-issued-api-key.StatusCodes.json | 123 +---------
.../api/admin-get-issued-api-key.api.mdx | 68 ++++--
.../api/admin-get-jwks.RequestSchema.json | 2 +-
.../api/admin-get-jwks.StatusCodes.json | 43 +---
.../reference/api/admin-get-jwks.api.mdx | 64 +++--
.../admin-import-api-key.RequestSchema.json | 92 +------
.../api/admin-import-api-key.StatusCodes.json | 136 +----------
.../api/admin-import-api-key.api.mdx | 70 ++++--
.../admin-issue-api-key.RequestSchema.json | 73 +-----
.../api/admin-issue-api-key.StatusCodes.json | 137 +----------
.../reference/api/admin-issue-api-key.api.mdx | 69 ++++--
...-list-imported-api-keys.ParamsDetails.json | 23 +-
...-list-imported-api-keys.RequestSchema.json | 2 +-
...in-list-imported-api-keys.StatusCodes.json | 146 +-----------
.../api/admin-list-imported-api-keys.api.mdx | 68 ++++--
...in-list-issued-api-keys.ParamsDetails.json | 23 +-
...in-list-issued-api-keys.RequestSchema.json | 2 +-
...dmin-list-issued-api-keys.StatusCodes.json | 139 +----------
.../api/admin-list-issued-api-keys.api.mdx | 69 ++++--
.../admin-revoke-api-key.ParamsDetails.json | 11 +-
.../admin-revoke-api-key.RequestSchema.json | 35 +--
.../api/admin-revoke-api-key.StatusCodes.json | 37 +--
.../api/admin-revoke-api-key.api.mdx | 69 ++++--
...n-rotate-issued-api-key.ParamsDetails.json | 12 +-
...n-rotate-issued-api-key.RequestSchema.json | 78 +-----
...min-rotate-issued-api-key.StatusCodes.json | 224 +-----------------
.../api/admin-rotate-issued-api-key.api.mdx | 78 ++++--
...update-imported-api-key.ParamsDetails.json | 12 +-
...update-imported-api-key.RequestSchema.json | 57 +----
...n-update-imported-api-key.StatusCodes.json | 126 +---------
.../api/admin-update-imported-api-key.api.mdx | 67 ++++--
...n-update-issued-api-key.ParamsDetails.json | 11 +-
...n-update-issued-api-key.RequestSchema.json | 54 +----
...min-update-issued-api-key.StatusCodes.json | 123 +---------
.../api/admin-update-issued-api-key.api.mdx | 68 ++++--
.../admin-verify-api-key.RequestSchema.json | 22 +-
.../api/admin-verify-api-key.StatusCodes.json | 114 +--------
.../api/admin-verify-api-key.api.mdx | 78 ++++--
.../api/batch-verify-api-keys.api.mdx | 45 ----
.../reference/api/ory-talos-api.info.mdx | 38 +--
.../api/revoke-api-key.RequestSchema.json | 37 +--
.../api/revoke-api-key.StatusCodes.json | 41 +---
.../reference/api/revoke-api-key.api.mdx | 73 ++++--
docs/talos/reference/api/sidebar.ts | 18 +-
.../reference/api/verify-api-key.api.mdx | 42 ----
.../reference/cli/talos-jwk-generate-ecdsa.md | 9 +-
.../reference/cli/talos-jwk-generate-eddsa.md | 7 +-
.../reference/cli/talos-jwk-generate-hmac.md | 9 +-
.../reference/cli/talos-jwk-generate-rsa.md | 7 +-
.../talos/reference/cli/talos-jwk-generate.md | 12 +-
docs/talos/reference/cli/talos-jwk-get.md | 23 +-
docs/talos/reference/cli/talos-jwk.md | 12 +-
.../reference/cli/talos-keys-batch-verify.md | 4 +-
.../reference/cli/talos-keys-derive-token.md | 8 +-
.../cli/talos-keys-imported-batch-import.md | 4 +-
.../cli/talos-keys-imported-delete.md | 4 +-
.../reference/cli/talos-keys-imported-get.md | 4 +-
.../cli/talos-keys-imported-import.md | 4 +-
.../reference/cli/talos-keys-imported-list.md | 4 +-
.../cli/talos-keys-imported-revoke.md | 4 +-
.../reference/cli/talos-keys-imported.md | 16 +-
docs/talos/reference/cli/talos-keys-issue.md | 4 +-
.../reference/cli/talos-keys-issued-get.md | 4 +-
.../reference/cli/talos-keys-issued-issue.md | 4 +-
.../reference/cli/talos-keys-issued-list.md | 4 +-
.../reference/cli/talos-keys-issued-rotate.md | 4 +-
.../reference/cli/talos-keys-issued-update.md | 4 +-
docs/talos/reference/cli/talos-keys-issued.md | 14 +-
docs/talos/reference/cli/talos-keys-revoke.md | 4 +-
.../reference/cli/talos-keys-self-revoke.md | 4 +-
docs/talos/reference/cli/talos-keys-verify.md | 4 +-
docs/talos/reference/cli/talos-keys.md | 20 +-
.../talos/reference/cli/talos-migrate-down.md | 7 +-
.../reference/cli/talos-migrate-force.md | 14 +-
.../reference/cli/talos-migrate-status.md | 11 +-
docs/talos/reference/cli/talos-migrate-up.md | 9 +-
docs/talos/reference/cli/talos-migrate.md | 12 +-
docs/talos/reference/cli/talos-proxy.md | 34 ++-
docs/talos/reference/cli/talos-serve-admin.md | 9 +-
docs/talos/reference/cli/talos-serve-check.md | 8 +-
docs/talos/reference/cli/talos-serve.md | 13 +-
docs/talos/reference/cli/talos.md | 23 +-
docs/talos/reference/config.md | 40 ++--
docs/talos/reference/error-codes.md | 10 +-
docs/talos/reference/events.md | 17 +-
docs/talos/reference/index.md | 5 +
docs/talos/reference/token-format.md | 56 +++--
src/sidebar.ts | 5 +-
157 files changed, 2639 insertions(+), 4023 deletions(-)
delete mode 100644 docs/talos/reference/api/batch-verify-api-keys.api.mdx
delete mode 100644 docs/talos/reference/api/verify-api-key.api.mdx
diff --git a/docs/talos/CLAUDE.md b/docs/talos/CLAUDE.md
index b69f422175..3f89f4321f 100644
--- a/docs/talos/CLAUDE.md
+++ b/docs/talos/CLAUDE.md
@@ -5,14 +5,15 @@
Use `jq` instead of `python3` for all JSON operations in code examples:
- **Pretty-print:** `| jq .` not `| python3 -m json.tool`
-- **Extract fields:** `| jq -r '.field'` not `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
+- **Extract fields:** `| jq -r '.field'` not
+ `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
-**Never write curl output to temporary files.** Capture responses in shell variables instead. File-based operations fail when
-`/tmp` doesn't exist or isn't writable.
+**Never write curl output to temporary files.** Capture responses in shell variables instead.
+File-based operations fail when `/tmp` doesn't exist or isn't writable.
```bash
# Good: variable-based
-RESPONSE=$(curl -s -X POST "$URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name": "my-key"}')
echo "$RESPONSE" | jq .
@@ -27,8 +28,8 @@ rm -f /tmp/response.json
## API Field Documentation
-Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or enum tables. These are maintained
-in the canonical references:
+Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or
+enum tables. These are maintained in the canonical references:
- **Field tables** -> auto-generated API reference at `reference/api/*.api.mdx`
- **Error codes** -> `reference/error-codes.md`
@@ -36,9 +37,10 @@ in the canonical references:
### What belongs in integration guides
- **Workflow and examples**: curl commands, step-by-step instructions, the "how" and "why"
-- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The response includes a `secret` field
- -- store it securely")
-- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT vs macaroon)
+- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The
+ response includes a `secret` field -- store it securely")
+- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT
+ vs macaroon)
- **Operational constraints**: limits, cache control headers, retry strategies
- **Links to reference**: always link to the canonical source for complete field/error details
@@ -51,8 +53,9 @@ in the canonical references:
### Link format
-**All links MUST be relative links to markdown/mdx files with the file extension.** Never use absolute links (starting with `/`)
-or links without a file extension. Hashbang anchors are allowed after the file extension.
+**All links MUST be relative links to markdown/mdx files with the file extension.** Never use
+absolute links (starting with `/`) or links without a file extension. Hashbang anchors are allowed
+after the file extension.
- Links to `.md` files: `[text](../reference/error-codes.md#section)`
- Links to `.api.mdx` files: `[text](../reference/api/admin-issue-api-key.api.mdx)`
@@ -85,11 +88,13 @@ Ensure that notes / callouts have two line breaks, or they will get formatted in
**Incorrect:**
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by
+external Go modules. :::
```
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by
+external Go modules. :::
```
Correct:
@@ -97,7 +102,8 @@ Correct:
```md
:::note
-Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules.
+Internal package The Go client is in an `internal/` package and cannot be imported by external Go
+modules.
:::
```
diff --git a/docs/talos/concepts/architecture.md b/docs/talos/concepts/architecture.md
index 98fa68ec94..b0ba17fa0c 100644
--- a/docs/talos/concepts/architecture.md
+++ b/docs/talos/concepts/architecture.md
@@ -8,20 +8,17 @@ Talos separates API key management into two planes.
## Admin plane
-The admin plane handles all write operations: key issuance, rotation, revocation, token derivation, and JWKS. It is typically
-exposed only to internal services.
+The admin plane handles all write operations: key issuance, rotation, revocation, token derivation,
+and JWKS. It is typically exposed only to internal services.
-Endpoints: `/v2/admin/`
+Endpoints: `/v2alpha1/admin/`
## Data plane
-The data plane handles high-throughput read operations: key verification, batch verification, and self-revocation. It is designed
-for low-latency edge deployment.
+The data plane handles high-throughput read operations: key verification, batch verification, and
+self-revocation. It is designed for low-latency edge deployment.
-Primary endpoints: `/v2/apiKeys:verify`, `/v2/apiKeys:batchVerify`, `/v2/apiKeys:selfRevoke`
-
-Admin-scoped verification endpoints also exist for operator workflows, including `/v2/admin/apiKeys:verify` and
-`/v2/admin/apiKeys:batchVerify`, but the self-service paths are the primary data-plane surface for credential holders.
+Endpoints: `/v2alpha1/admin/apiKeys:verify`, `/v2alpha1/admin/apiKeys:batchVerify`, `/v2alpha1/apiKeys:selfRevoke`
## Request flow
@@ -31,7 +28,7 @@ Client --> Data Plane --> Cache (hit?) --> Database --> Response
+-- cache hit ---------------+
```
-1. Client sends credential to `POST /v2/apiKeys:verify`
+1. Client sends credential to `POST /v2alpha1/admin/apiKeys:verify`
2. Talos identifies the credential type (generated, imported, JWT, macaroon)
3. For generated keys, the UUID is extracted from the token identifier
4. For imported keys, a tenant-scoped SHA-512/256 hash is computed
@@ -46,7 +43,8 @@ Client --> Data Plane --> Cache (hit?) --> Database --> Response
| Split planes | Commercial | Admin and data planes as separate deployments |
| Edge proxy | Commercial | Data plane at the edge with local cache |
-Both planes share the same database. The data plane can use caching (memory or Redis) to minimize database load.
+Both planes share the same database. The data plane can use caching (memory or Redis) to minimize
+database load.
## Ports
@@ -66,22 +64,22 @@ The system is divided into distinct layers:
- **Persistence layer**: Database abstraction with pluggable drivers
- **Cache layer**: Performance optimization with multiple backends
-This separation allows independent scaling of components, different SLOs for different operations (admin targets \<100ms p99, data
-plane targets \<3ms p99), and clear boundaries between responsibilities.
+This separation allows independent scaling of components, different SLOs for different operations
+(admin targets \<100ms p99, data plane targets \<3ms p99), and clear boundaries between
+responsibilities.
### Production-first design
-Inspired by proven systems like SpiceDB and Kubernetes:
-
- Hard isolation between admin and data operations
-- Comprehensive observability (metrics, traces, logs) built in from the start
-- Graceful degradation and failure handling
-- Zero-downtime deployments
+- Metrics, traces, and structured logs are emitted by default
+- Graceful degradation when the database or cache backend is unavailable
+- Zero-downtime deployments via rolling updates and stateless verification
-### Performance by default
+### Performance characteristics
- Self-contained tokens (JWT/macaroon) enable stateless verification
-- HMAC-SHA256 for fast revocation checks -- not bcrypt, which would limit throughput to ~10 req/sec per core
+- HMAC-SHA256 keeps the revocation check on the order of microseconds; bcrypt
+ would cap a single core at roughly 10 verifications per second
- LRU caching for hot paths
- Minimal allocations in the verification path
@@ -128,21 +126,21 @@ Clients (CLI, SDK, HTTP)
+-----------+ +-----------+
```
-All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through middleware for logging,
-metrics, and tracing before being routed to the appropriate plane.
+All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through
+middleware for logging, metrics, and tracing before being routed to the appropriate plane.
## Component overview
### HTTP server
-The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both planes through a single port,
-handles CORS and compression, and exposes OpenAPI documentation.
+The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both
+planes through a single port, handles CORS and compression, and exposes OpenAPI documentation.
### Service layer
-Business logic is split between the admin plane service (key lifecycle, import, token derivation, input validation) and the data
-plane verifier (token parsing, signature verification, revocation checking, cache management). The verifier is optimized for the
-hot path with minimal allocations.
+Business logic is split between the admin plane service (key lifecycle, import, token derivation,
+input validation) and the data plane verifier (token parsing, signature verification, revocation
+checking, cache management). The verifier is optimized for the hot path with minimal allocations.
### Persistence
@@ -173,22 +171,25 @@ Talos supports multiple JWT signing algorithms and a separate API key hashing me
- **API key hashing**
- `HMAC-SHA256` -- used for API key revocation checks (\<1ms with constant-time comparison)
-The JWT signing algorithm is determined per JWK by its `alg` field, so one JWKS can contain keys for multiple signing algorithms
-at the same time.
+The JWT signing algorithm is determined per JWK by its `alg` field, so one JWKS can contain keys for
+multiple signing algorithms at the same time.
### Observability
Built-in instrumentation across three pillars:
-- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate counters
-- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and Jaeger exporters
+- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate
+ counters
+- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and
+ Jaeger exporters
- **Logging** -- structured JSON logging via slog with correlation IDs and contextual fields
## Scalability
### Small (\<1k RPS)
-A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external dependencies required.
+A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external
+dependencies required.
- OSS edition sufficient
- 1 CPU, 512MB RAM
@@ -196,8 +197,8 @@ A single Talos instance handles both planes with SQLite and an in-memory LRU cac
### Medium (10-50k RPS)
-Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for durability. Redis provides shared
-caching across data plane instances.
+Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for
+durability. Redis provides shared caching across data plane instances.
- Commercial edition
- Auto-scaling for data plane
@@ -205,8 +206,8 @@ caching across data plane instances.
### Large (200k+ RPS)
-A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis cache and PostgreSQL with read
-replicas and connection pooling. Supports multi-region deployment.
+A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis
+cache and PostgreSQL with read replicas and connection pooling. Supports multi-region deployment.
- Commercial edition
- Regional data plane deployment
diff --git a/docs/talos/concepts/caching.md b/docs/talos/concepts/caching.md
index 707688901f..81d02e7382 100644
--- a/docs/talos/concepts/caching.md
+++ b/docs/talos/concepts/caching.md
@@ -4,12 +4,14 @@ title: Caching and consistency
# Caching and consistency
-Talos can cache verification results to reduce database load and improve latency.
+Talos caches verification results to reduce database load and improve latency. The OSS edition
+ships a no-op cache; in-memory and Redis backends are commercial-only — see
+[Caching](../operate/cache/index.md) for backend selection.
## How it works
-When caching is enabled, the first verification request for a key hits the database. Subsequent requests within the cache TTL are
-served from cache without a database lookup.
+When caching is enabled, the first verification request for a key hits the database. Subsequent
+requests within the cache TTL are served from cache without a database lookup.
## Cache types
@@ -22,24 +24,24 @@ served from cache without a database lookup.
Caching introduces eventual consistency for revocation:
-1. Admin revokes a key via `POST /v2/admin/apiKeys/{id}:revoke`
+1. Admin revokes a key via `POST /v2alpha1/admin/apiKeys/{key_id}:revoke`
2. The revocation takes effect in the database immediately
3. Cached verification results for that key remain valid until the cache entry expires
-4. After TTL expiry, the next verification hits the database and returns `active: false`
+4. After TTL expiry, the next verification hits the database and returns `is_active: false`
## Cache bypass
To force a database lookup (bypassing cache), include the `Cache-Control: no-cache` header:
```bash
-curl -X POST http://localhost:4420/v2/admin/apiKeys:verify \
+curl -X POST http://localhost:4420/v2alpha1/admin/apiKeys:verify \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{"credential": "..."}'
```
-See the [quickstart revocation check](../quickstart/index.md) and the [curl SDK reference](../integrate/sdk/curl.md) for tested
-examples using cache bypass.
+See the [quickstart revocation check](../quickstart/index.md) and the
+[curl SDK reference](../integrate/sdk/curl.md) for tested examples using cache bypass.
## TTL guidelines
diff --git a/docs/talos/concepts/credential-types.md b/docs/talos/concepts/credential-types.md
index ae01b7d3ca..eb3eec8a95 100644
--- a/docs/talos/concepts/credential-types.md
+++ b/docs/talos/concepts/credential-types.md
@@ -8,31 +8,35 @@ Talos manages four credential types.
## Issued API keys
-Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable TTL. The key ID (UUID) is
-embedded in the token for direct database lookup. The full secret is returned once at creation.
+Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable
+TTL. The key ID (UUID) is embedded in the token for direct database lookup. The full secret is
+returned once at creation.
**Lifecycle**: Issue, rotate, update metadata, revoke.
## Imported API keys
External credentials (Stripe, GitHub, etc.) stored by hash. Any string format accepted. Talos stores
-`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and scopes as issued keys.
+`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and
+scopes as issued keys.
**Lifecycle**: Import, update metadata, revoke, delete.
## Derived JWTs
-Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg` field in the JWK (EdDSA or
-RS256). Can be verified independently using the JWKS endpoint (`GET /v2/admin/.well-known/jwks.json`). Claims include `key_id`,
-`actor_id`, scopes, and expiration.
+Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg`
+field in the JWK (EdDSA or RS256). Can be verified independently using the JWKS endpoint
+(`GET /v2alpha1/admin/derivedKeys/jwks.json`). Claims include `key_id`, `actor_id`, scopes, and
+expiration.
## Derived macaroons
-Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and contextual attenuation.
+Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and
+contextual attenuation.
## Credential routing
-When a credential is submitted to `/v2/apiKeys:verify`, Talos identifies the type automatically by its format and routes it to the
-appropriate verification handler. The admin-scoped verify endpoint uses the same credential routing logic. See the
-[credential routing table](../reference/token-format.md#credential-routing) for the full format-to-type mapping and lookup
-methods.
+When a credential is submitted to `/v2alpha1/admin/apiKeys:verify`, Talos identifies the type
+automatically by its format and routes it to the appropriate verification handler. See the
+[credential routing table](../reference/token-format.md#credential-routing) for the full
+format-to-type mapping and lookup methods.
diff --git a/docs/talos/concepts/index.md b/docs/talos/concepts/index.md
index 6ae6bef95b..6b57a7b962 100644
--- a/docs/talos/concepts/index.md
+++ b/docs/talos/concepts/index.md
@@ -11,6 +11,7 @@ Core ideas behind Ory Talos.
- [Token format](token-format.md) — v1 key format specification
- [Security model](security-model.md) — cryptographic primitives and tenant isolation
- [Caching and consistency](caching.md) — verification caching and revocation propagation
-- [Token derivation security](token-derivation-security.md) — stateless verification and revocation semantics
+- [Token derivation security](token-derivation-security.md) — stateless verification and revocation
+ semantics
- [Rate limiting](rate-limiting.md) — rate limit metadata on API keys
- [IP restrictions](ip-restrictions.md) — CIDR-based access control for API keys
diff --git a/docs/talos/concepts/ip-restrictions.md b/docs/talos/concepts/ip-restrictions.md
index dce06df1d9..6278eaf2a7 100644
--- a/docs/talos/concepts/ip-restrictions.md
+++ b/docs/talos/concepts/ip-restrictions.md
@@ -5,9 +5,10 @@ description: CIDR-based allowlists that restrict which client IPs can use an API
# IP restrictions
-Talos supports per-key IP restrictions that limit which client IP addresses can use an API key. Restrictions are defined as a list
-of CIDR ranges (for example, `192.168.1.0/24` or `2001:db8::/32`). Only requests originating from an IP within the allowlist are
-accepted. Keys without IP restrictions accept traffic from any address.
+Talos supports per-key IP restrictions that limit which client IP addresses can use an API key.
+Restrictions are defined as a list of CIDR ranges (for example, `192.168.1.0/24` or
+`2001:db8::/32`). Only requests originating from an IP within the allowlist are accepted. Keys
+without IP restrictions accept traffic from any address.
## How IP restrictions work
@@ -15,9 +16,9 @@ IP restriction enforcement has two stages: **IP resolution** and **CIDR matching
### IP resolution
-When a verification request arrives, Talos captures all IP-related headers from the HTTP request into context through middleware.
-At verification time, the configured **client IP source** determines which header to use for extracting the client address. The
-available sources are:
+When a verification request arrives, Talos captures all IP-related headers from the HTTP request
+into context through middleware. At verification time, the configured **client IP source**
+determines which header to use for extracting the client address. The available sources are:
| Source | Header / value used | Typical use case |
| ------------------ | ---------------------------- | -------------------------------------- |
@@ -27,32 +28,33 @@ available sources are:
| `X_REAL_IP` | `X-Real-Ip` | Behind NGINX with `proxy_set_header` |
| `TRUE_CLIENT_IP` | `True-Client-Ip` | Behind Akamai or Cloudflare Enterprise |
-If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is set once at startup and
-applies to all verification requests.
+If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is
+set once at startup and applies to all verification requests.
### CIDR matching
-After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP falls within any of the ranges.
-Both IPv4 and IPv6 CIDR notation are supported (for example, `10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32`
-(IPv4) or `/128` (IPv6) range.
+After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP
+falls within any of the ranges. Both IPv4 and IPv6 CIDR notation are supported (for example,
+`10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32` (IPv4) or `/128` (IPv6) range.
-If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification fails with error code
-`VERIFICATION_ERROR_IP_NOT_ALLOWED`.
+If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification
+fails with error code `VERIFICATION_ERROR_IP_NOT_ALLOWED`.
## Fail-closed behavior
-IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for example, because the request context
-does not contain IP metadata -- the verification request is denied. This prevents accidental access when header forwarding is
-misconfigured.
+IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for
+example, because the request context does not contain IP metadata -- the verification request is
+denied. This prevents accidental access when header forwarding is misconfigured.
-This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking legitimate traffic during limiter
-outages.
+This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking
+legitimate traffic during limiter outages.
## Cache interaction
-Cached verification results still contain the key's allowed CIDR list. When a cached key is returned, Talos re-evaluates the IP
-restriction against the **current request's** client IP before returning a success response. This means IP restrictions are
-enforced on every request, regardless of whether the result came from cache or the database.
+Cached verification results still contain the key's allowed CIDR list. When a cached key is
+returned, Talos re-evaluates the IP restriction against the **current request's** client IP before
+returning a success response. This means IP restrictions are enforced on every request, regardless
+of whether the result came from cache or the database.
The enforcement sequence is:
@@ -64,24 +66,29 @@ The enforcement sequence is:
## IPv4 and IPv6 support
-IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same allowlist. Talos parses client
-addresses using Go's `net.ParseIP`, which handles both formats transparently. There is no implicit mapping between IPv4 and IPv6
--- a `10.0.0.0/8` range does not match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
+IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same
+allowlist. Talos parses client addresses using Go's `net.ParseIP`, which handles both formats
+transparently. There is no implicit mapping between IPv4 and IPv6 -- a `10.0.0.0/8` range does not
+match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
## Key concepts
-- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is denied. Keys without
- restrictions accept all IPs.
+- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is
+ denied. Keys without restrictions accept all IPs.
- **Per-key granularity** -- each key has its own CIDR list. Keys do not share IP restrictions.
-- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured proxies cannot bypass restrictions.
-- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32` (IPv4) or `/128` (IPv6).
-- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside the key's allowed ranges. See
- the [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is served from cache.
+- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured
+ proxies cannot bypass restrictions.
+- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32`
+ (IPv4) or `/128` (IPv6).
+- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside
+ the key's allowed ranges. See the
+ [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
+- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is
+ served from cache.
## Next steps
- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
- [Configuration reference](../reference/config.md) -- client IP source and related settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
- `VERIFICATION_ERROR_IP_NOT_ALLOWED`
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
+ error codes including `VERIFICATION_ERROR_IP_NOT_ALLOWED`
diff --git a/docs/talos/concepts/rate-limiting.md b/docs/talos/concepts/rate-limiting.md
index d411347253..76ce2a560a 100644
--- a/docs/talos/concepts/rate-limiting.md
+++ b/docs/talos/concepts/rate-limiting.md
@@ -1,33 +1,38 @@
---
title: Rate limiting
-description: Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
+description:
+ Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
---
# Rate limiting
-Talos supports per-key rate limit policies that control how many requests a key can make within a time window. A rate limit policy
-consists of two fields: a **quota** (maximum request count) and a **window** (time period in seconds). Keys without a policy are
-never rate limited.
+Talos supports per-key rate limit policies that control how many requests a key can make within a
+time window. A rate limit policy consists of two fields: a **quota** (maximum request count) and a
+**window** (time period in seconds). Keys without a policy are never rate limited.
How enforcement works depends on your edition.
## OSS edition: metadata and headers
-In the OSS edition, Talos stores rate limit policies on keys and returns them in verification responses. It does not enforce
-limits itself. Your API gateway or reverse proxy reads the policy from the response headers and applies enforcement externally.
+In the OSS edition, Talos stores rate limit policies on keys and returns them in verification
+responses. It does not enforce limits itself. Your API gateway or reverse proxy reads the policy
+from the response headers and applies enforcement externally.
-This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy, NGINX, Kong, or a dedicated
-service). Verification responses include IETF-format headers that gateways can consume directly:
+This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy,
+NGINX, Kong, or a dedicated service). Verification responses include IETF-format headers that
+gateways can consume directly:
- **`RateLimit-Policy`** -- declares the key's quota and window (e.g., `"default";q=100;w=60`).
- **`RateLimit`** -- reports remaining quota (e.g., `"default";r=42`).
## Commercial edition: server-side enforcement
-The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the verification response returns
-`is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`. The HTTP status remains **200** because the verification
-endpoint always returns a structured response — the rate limit status is conveyed through the response body, not the HTTP status
-code. This design allows gateways to distinguish transport errors from application-level rate limiting decisions.
+The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the
+verification response returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`.
+The HTTP status remains **200** because the verification endpoint always returns a structured
+response — the rate limit status is conveyed through the response body, not the HTTP status code.
+This design allows gateways to distinguish transport errors from application-level rate limiting
+decisions.
### Backends
@@ -38,15 +43,15 @@ The commercial edition supports two enforcement backends:
| `memory` | GCRA | Single process (not shared) | Lost on restart |
| `redis` | GCRA | Shared across all connected pods | Survives restarts |
-Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate limiting without the
-boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp per key and allows requests as long as the average
-rate stays within the configured quota.
+Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate
+limiting without the boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp
+per key and allows requests as long as the average rate stays within the configured quota.
-**Memory** is suited for single-node deployments or development. Each process maintains independent counters per key, so state is
-not shared across pods.
+**Memory** is suited for single-node deployments or development. Each process maintains independent
+counters per key, so state is not shared across pods.
-**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the same Redis instance. State
-survives process restarts as long as Redis is available.
+**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the
+same Redis instance. State survives process restarts as long as Redis is available.
### Configuration
@@ -56,14 +61,16 @@ rate_limit:
backend: memory # Requires restart: changes the backend type
```
-- **`rate_limit.enabled`** is checked on every verification request through the config provider. You can toggle it at runtime by
- editing the config file -- Talos picks up the change automatically.
-- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this value requires a restart because
- it initializes different infrastructure (in-memory maps vs. Redis connections).
+- **`rate_limit.enabled`** is checked on every verification request through the config provider. You
+ can toggle it at runtime by editing the config file -- Talos picks up the change automatically.
+- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this
+ value requires a restart because it initializes different infrastructure (in-memory maps vs. Redis
+ connections).
## HTTP response headers
-When a key has a rate limit policy, verification responses include IETF draft-compliant headers regardless of edition:
+When a key has a rate limit policy, verification responses include IETF draft-compliant headers
+regardless of edition:
| Header | Description | Example |
| ------------------ | --------------------------------------------------- | ---------------------- |
@@ -71,29 +78,32 @@ When a key has a rate limit policy, verification responses include IETF draft-co
| `RateLimit` | Reports remaining quota | `"default";r=42` |
| `Retry-After` | Seconds to wait before retrying (only when limited) | `18` |
-Gateways and clients can use these headers for both external enforcement (OSS) and client-side backoff (Commercial).
+Gateways and clients can use these headers for both external enforcement (OSS) and client-side
+backoff (Commercial).
## Fail-open behavior
-If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos **fails open**: verification
-succeeds but rate limit metadata is omitted from the response. This design prevents limiter outages from blocking legitimate
-traffic.
+If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos
+**fails open**: verification succeeds but rate limit metadata is omitted from the response. This
+design prevents limiter outages from blocking legitimate traffic.
## Key concepts
- **Per-key isolation** -- each key has its own counter. Keys do not share rate limit budgets.
-- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g. `"60s"`). Both must be set for
- enforcement to apply.
-- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate limiting.
-- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota (Commercial only). See the
+- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g.
+ `"60s"`). Both must be set for enforcement to apply.
+- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate
+ limiting.
+- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota
+ (Commercial only). See the
[error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification result that is still valid will
- be returned without consulting the rate limiter.
+- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification
+ result that is still valid will be returned without consulting the rate limiter.
## Next steps
-- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify rate-limited keys, and handle quota
- exhaustion
+- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify
+ rate-limited keys, and handle quota exhaustion
- [Configuration reference](../reference/config.md) -- all `rate_limit.*` settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
- `VERIFICATION_ERROR_RATE_LIMITED`
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
+ error codes including `VERIFICATION_ERROR_RATE_LIMITED`
diff --git a/docs/talos/concepts/security-model.md b/docs/talos/concepts/security-model.md
index b65d624ec4..d491f65c87 100644
--- a/docs/talos/concepts/security-model.md
+++ b/docs/talos/concepts/security-model.md
@@ -6,17 +6,47 @@ title: Security model
## Cryptographic primitives
-| Purpose | Algorithm |
-| -------------------- | ------------------------------------------------------- |
-| API key checksum | HMAC-SHA256 (truncated to 64 bits) |
-| Imported key hashing | SHA-512/256 with tenant salt |
-| JWT signing | EdDSA (Ed25519) or RS256, determined by JWK `alg` field |
-| Macaroon binding | HMAC-SHA256 |
+| Purpose | Algorithm | Keyed by |
+| ----------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
+| API key checksum | HMAC-SHA256 (full 32-byte digest, base58-encoded) | `secrets.hmac.current` |
+| Imported key hashing | SHA-512/256 over `nid \|\| 0x00 \|\| raw_key` | Tenant `nid` (no shared secret) |
+| Macaroon root-key derivation | HMAC-SHA256 with domain `"talos/macaroon/v1/root-key"` | `secrets.hmac.current` |
+| Macaroon caveat binding | HMAC-SHA256 (libmacaroons V2) | Derived macaroon root key |
+| JWT signing | EdDSA (Ed25519) or RS256, determined by JWK `alg` | JWKS at `credentials.derived_tokens.jwt.jwks.urls` |
+| Pagination-token encryption | NaCl secretbox (XSalsa20-Poly1305) keyed by SHA-256(secret) | `secrets.pagination.current` (falls back to `secrets.default.current`) |
+
+`secrets.hmac.current` is shared between the API key checksum and the macaroon root key. Rotating
+it rotates both at once; verification falls back through `secrets.hmac.retired` for both purposes.
+Pagination secrets are completely independent from `secrets.hmac.*`. See
+[Secret management](../operate/secrets.md).
+
+## JWT signing key selection
+
+The data plane resolves the active signing key on every derive request:
+
+1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK with the
+ matching `kid`. If no JWK in the configured JWKS has that `kid`, signing fails with
+ `InternalError` and `signing_key_id` is included in the error details.
+2. Otherwise, Talos prefers the first key with `"use": "sig"`.
+3. Otherwise, Talos returns the first key in the JWKS.
+
+Set `signing_key_id` explicitly in production so rotation becomes a config change rather than a
+JWKS-ordering side effect. Multi-tenant deployments resolve the JWKS per tenant via the
+contextualizer; the `kid` hint is also per-tenant.
## Secret rotation
-Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the old one to `retired`. During
-verification, all secrets are tried in order.
+Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the
+old one to `retired`. During verification, all secrets in the same family are tried in order.
+
+- **HMAC rotation** (`secrets.hmac.*`) rotates both the API key checksum and the macaroon root
+ key. Existing API keys and macaroons remain valid as long as the previous secret is in
+ `retired`.
+- **Pagination rotation** (`secrets.pagination.*` or `secrets.default.*`) only affects
+ `next_page_token` values. Outstanding tokens decode for as long as the previous secret stays
+ in `retired`.
+
+The two families are independent. Rotate them on independent schedules.
## Tenant isolation
@@ -24,12 +54,14 @@ Multi-tenant deployments use Network IDs (NID) for data isolation:
- **Database**: Composite primary keys `(nid, key_id)` prevent cross-tenant access
- **Token claims**: NID is embedded in derived tokens and validated during verification
-- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different hashes per tenant
+- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different
+ hashes per tenant
## Cache security
-Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis keys, or memory cache entries.
-This prevents credential leakage through cache inspection, Redis `MONITOR` commands, or memory dumps.
+Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis
+keys, or memory cache entries. This prevents credential leakage through cache inspection, Redis
+`MONITOR` commands, or memory dumps.
- **Cache key format:** `namespace:nid:sha256(credential)` -- deterministic, no plaintext
- **Reverse index:** Stores `key_id → sha256(credential)` for invalidation lookups -- no raw secrets
@@ -37,25 +69,28 @@ This prevents credential leakage through cache inspection, Redis `MONITOR` comma
## Admin/data plane separation
-The admin plane (key management) and data plane (verification) can be deployed separately. The admin plane should be restricted to
-internal networks. The data plane can be exposed publicly.
+The admin plane (key management) and data plane (verification) can be deployed separately. The admin
+plane should be restricted to internal networks. The data plane can be exposed publicly.
## Key lifecycle
-Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is irreversible. Expired keys are rejected
-during verification.
+Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is
+irreversible. Expired keys are rejected during verification.
## Why HMAC over bcrypt
-Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen passwords with ~40-60 bits of
-entropy). They use intentional slowness (~100ms per hash) to make brute-force attacks against weak passwords expensive.
+Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen
+passwords with ~40-60 bits of entropy). They use intentional slowness (~100ms per hash) to make
+brute-force attacks against weak passwords expensive.
-API keys are fundamentally different. They are **cryptographically random** with 128+ bits of entropy, making dictionary attacks
-impossible. The key space of 2^128 (340 undecillion combinations) renders brute force infeasible regardless of hashing speed.
+API keys are fundamentally different. They are **cryptographically random** with 128+ bits of
+entropy, making dictionary attacks impossible. The key space of 2^128 (~3.4 × 10^38) renders brute
+force infeasible regardless of hashing speed.
-HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the database. A database breach alone is
-insufficient to verify candidate keys -- the attacker must also compromise the secret. This provides a stronger security boundary
-than bcrypt, which stores everything needed for verification in the database itself.
+HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the
+database. A database breach alone is insufficient to verify candidate keys -- the attacker must also
+compromise the secret. This provides a stronger security boundary than bcrypt, which stores
+everything needed for verification in the database itself.
### Performance comparison
@@ -70,11 +105,11 @@ This yields a roughly **1,000x cost reduction** in compute for verification work
### Attack model
-**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault). Without the secret, they cannot
-verify any candidate key against the stored hashes.
+**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault).
+Without the secret, they cannot verify any candidate key against the stored hashes.
-**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes exhaustive search
-computationally infeasible with current or foreseeable technology.
+**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes
+exhaustive search computationally infeasible with current or foreseeable technology.
## Why Ed25519 for token signing
@@ -87,29 +122,31 @@ Talos uses Ed25519 (EdDSA over Curve25519) as the default signing algorithm for
| Signature size | 64 bytes | 256 bytes |
| Security level | 128 bits | 112 bits |
-Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of implementation vulnerabilities
-(unlike ECDSA P-256, where a weak nonce leaks the private key). It is also constant-time by design, providing immunity to timing
-side-channel attacks.
+Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of
+implementation vulnerabilities (unlike ECDSA P-256, where a weak nonce leaks the private key). It is
+also constant-time by design, providing immunity to timing side-channel attacks.
-RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not support EdDSA. The signing
-algorithm is determined by the `alg` field in the JWK configuration.
+RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not
+support EdDSA. The signing algorithm is determined by the `alg` field in the JWK configuration.
## Security requirements
For the cryptographic model to hold, the following operational requirements must be met:
-1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g., HashiCorp Vault, AWS Secrets
- Manager). It must never be stored in the database or committed to version control. Talos supports zero-downtime rotation by
- maintaining current and retired secrets.
+1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g.,
+ HashiCorp Vault, AWS Secrets Manager). It must never be stored in the database or committed to
+ version control. Talos supports zero-downtime rotation by maintaining current and retired
+ secrets.
-2. **Key entropy** -- API keys must be generated using a cryptographically secure random number generator with at least 128 bits
- of entropy. Talos generates keys internally; user-provided key material is not accepted for issued keys.
+2. **Key entropy** -- API keys must be generated using a cryptographically secure random number
+ generator with at least 128 bits of entropy. Talos generates keys internally; user-provided key
+ material is not accepted for issued keys.
-3. **Transport security** -- All communication must use TLS. API key secrets must never appear in URLs, query parameters, or log
- output.
+3. **Transport security** -- All communication must use TLS. API key secrets must never appear in
+ URLs, query parameters, or log output.
-4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored securely and never exposed
- through API responses or logs.
+4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored
+ securely and never exposed through API responses or logs.
## Industry precedent
@@ -120,5 +157,5 @@ Major cloud providers use HMAC for API key authentication:
- **Stripe** -- HMAC for API authentication and webhook signature verification
- **GitHub** -- HMAC-SHA256 for webhook payload signatures
-These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and verification throughput is a
-critical operational requirement.
+These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and
+verification throughput is a critical operational requirement.
diff --git a/docs/talos/concepts/token-derivation-security.md b/docs/talos/concepts/token-derivation-security.md
index 65cc45521e..ab9f4f8874 100644
--- a/docs/talos/concepts/token-derivation-security.md
+++ b/docs/talos/concepts/token-derivation-security.md
@@ -7,20 +7,26 @@ description: Stateless verification model and revocation semantics for derived t
## Overview
-Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are **stateless capability tokens**:
-all security constraints are enforced at creation time, and verification requires no database access. This design gives
-predictable sub-millisecond verification, zero database load on the hot path, and straightforward edge deployment.
+Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are
+**stateless capability tokens**: all security constraints are enforced at creation time, and
+verification requires no database access. This design gives predictable sub-millisecond
+verification, zero database load on the hot path, and straightforward edge deployment.
## Creation-time enforcement
-When a token is derived via `POST /v2/tokens:derive`, all security constraints are enforced before the token is signed:
+When a token is derived via `POST /v2alpha1/tokens:derive`, all security constraints are enforced before
+the token is signed:
- **Parent key must be ACTIVE.** A revoked or expired parent key cannot produce new tokens.
-- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than the parent, never more.
-- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the parent key's expiration.
-- **Subject and owner are inherited.** These fields are copied from the parent and cannot be overridden.
+- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than
+ the parent, never more.
+- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the
+ parent key's expiration.
+- **Subject and owner are inherited.** These fields are copied from the parent and cannot be
+ overridden.
-If any constraint is violated, the derivation request fails with an appropriate error code. No token is issued.
+If any constraint is violated, the derivation request fails with an appropriate error code. No token
+is issued.
## Verification-time behavior
@@ -29,11 +35,13 @@ Verifying a derived token is purely cryptographic. The system checks:
1. **Signature validity** -- the token was signed by a trusted JWK signing key.
2. **Expiration** -- the `exp` claim has not passed.
-There are no database lookups, no parent key status checks, and no scope re-validation against the parent. This produces:
+There are no database lookups, no parent key status checks, and no scope re-validation against the
+parent. This produces:
- **Low latency.** Verification completes in 1-2 ms compared to 5-10 ms with database round-trips.
- **Zero database load.** Derived token verification never touches the database.
-- **Edge deployability.** Verification nodes need only the public JWK set, not a database connection.
+- **Edge deployability.** Verification nodes need only the public JWK set, not a database
+ connection.
- **High availability.** Verification is unaffected by database outages.
## Revocation model
@@ -41,25 +49,30 @@ There are no database lookups, no parent key status checks, and no scope re-vali
When a parent API key is revoked:
- **New derivations are blocked.** Any attempt to derive from the revoked parent returns an error.
-- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and the token has not expired.
-- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a revocation error.
+- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and
+ the token has not expired.
+- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a
+ revocation error.
This behavior is intentional. It provides:
-- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full TTL.
-- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions simultaneously.
+- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full
+ TTL.
+- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions
+ simultaneously.
- **Graceful degradation.** Downstream systems have time to transition before tokens expire.
## Immediate revocation strategies
-If your threat model requires faster invalidation of derived tokens, use one or more of these approaches:
+If your threat model requires faster invalidation of derived tokens, use one or more of these
+approaches:
-- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently with minimal overhead. This is
- the primary recommended approach.
-- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos. Check the deny list during your
- application's authorization step.
-- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature verification immediately. This
- invalidates all derived tokens, not just those from one parent.
+- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently
+ with minimal overhead. This is the primary recommended approach.
+- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos.
+ Check the deny list during your application's authorization step.
+- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature
+ verification immediately. This invalidates all derived tokens, not just those from one parent.
## TTL guidelines
@@ -70,15 +83,18 @@ If your threat model requires faster invalidation of derived tokens, use one or
| Sensitive operations | 1-5 min | Limits damage from token theft |
| Long-running batch jobs | Use parent key directly | Avoids re-derivation during long processes |
-Short TTLs are the simplest and most effective control. When combined with the stateless verification model, they give security
-properties equivalent to stateful parent-status checks without the latency or availability cost.
+Short TTLs are the simplest and most effective control. When combined with the stateless
+verification model, they give security properties equivalent to stateful parent-status checks
+without the latency or availability cost.
## Security properties
Derived tokens are capability tokens with time-bounded authority:
-1. **All constraints enforced at creation.** The token can only be issued if the parent passes all checks.
-2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered with.
+1. **All constraints enforced at creation.** The token can only be issued if the parent passes all
+ checks.
+2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered
+ with.
3. **Time-bounded exposure.** Short TTLs limit the window in which a compromised token is useful.
4. **Immutable claims.** Subject, owner, scopes, and expiry are sealed in the token.
5. **No privilege escalation.** Scopes can never exceed the parent's scopes at creation time.
diff --git a/docs/talos/concepts/token-format.md b/docs/talos/concepts/token-format.md
index 00519c7dd8..9651a6f663 100644
--- a/docs/talos/concepts/token-format.md
+++ b/docs/talos/concepts/token-format.md
@@ -21,9 +21,10 @@ Issued API keys follow a structured v1 format:
## How it works
-The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used for database lookup. The
-checksum is HMAC-SHA256 over the payload, enabling tamper detection.
+The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used
+for database lookup. The checksum is HMAC-SHA256 over the payload, enabling tamper detection.
-During verification, all configured secrets (current + retired) are tried, supporting zero-downtime secret rotation.
+During verification, all configured secrets (current + retired) are tried, supporting zero-downtime
+secret rotation.
See [Token format reference](../reference/token-format.md) for the full specification.
diff --git a/docs/talos/index.md b/docs/talos/index.md
index 34c67b0ef9..ca2edca1b5 100644
--- a/docs/talos/index.md
+++ b/docs/talos/index.md
@@ -5,11 +5,13 @@ slug: /
# Ory Talos
-Ory Talos is a high-performance API key management service. It handles the full lifecycle of API credentials: issuing keys,
-verifying them at low latency, deriving short-lived tokens (JWT and macaroon), and revoking access.
+Ory Talos is an API key management service. It handles the full lifecycle of API credentials:
+issuing keys, verifying them on the data plane, deriving short-lived tokens (JWT and macaroon), and
+revoking access. Verification is sub-millisecond on a warm cache and stays under 5 ms p99 against a
+local SQL backend on commodity hardware.
-Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations** (verify, self-revoke) so you
-can scale and secure each path independently.
+Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations**
+(verify, self-revoke) so you can scale and secure each path independently.
## Choose your path
@@ -18,7 +20,8 @@ can scale and secure each path independently.
You're a developer building an application that needs API key authentication. Start here:
- **[Quickstart](./quickstart/index.md)** — issue and verify your first API key in 5 minutes
-- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying, importing keys, and deriving tokens
+- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying,
+ importing keys, and deriving tokens
- **[Error handling](./integrate/error-handling.md)** — error codes and retry strategies
### I want to run Talos in production
@@ -26,21 +29,27 @@ You're a developer building an application that needs API key authentication. St
You're a platform engineer responsible for deploying and operating Talos. Start here:
- **[Install](./operate/install.md)** — binary install or build from source
-- **[Configure](./operate/configure.md)** — configuration file, environment variables, and hot-reload behavior
-- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane topologies
-- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and health endpoints
+- **[Configure](./operate/configure.md)** — configuration file, environment variables, and
+ hot-reload behavior
+- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane
+ topologies
+- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and
+ health endpoints
## Editions
-**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key lifecycle, token derivation,
-and CLI.
+**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key
+lifecycle, token derivation, and CLI.
-**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed caching (Redis, in-memory), edge
-proxy nodes, and the admin UI. Pages that cover commercial-only features are marked with a "Commercial" badge.
+**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed
+caching (Redis, in-memory), edge proxy nodes, and the admin UI. Pages that cover commercial-only
+features are marked with a "Commercial" badge.
## Learn more
-- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching behavior
-- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint documentation
+- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching
+ behavior
+- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint
+ documentation
- **[CLI reference](./reference/index.md)** — command-line tool documentation
- **[Configuration reference](./reference/config.md)** — all configuration keys and their defaults
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.md
index 5b9af68f86..f81bda5d11 100644
--- a/docs/talos/integrate/batch-operations.md
+++ b/docs/talos/integrate/batch-operations.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Batch operations
-Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in parallel and return per-item
-results.
+Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in
+parallel and return per-item results.
@@ -40,12 +40,12 @@ echo "Keys issued"
```bash
-KEY1=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+KEY1=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"batch-key-1","actor_id":"user_1","scopes":["read"]}' | \
jq -r '.secret')
-KEY2=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+KEY2=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"batch-key-2","actor_id":"user_2","scopes":["write"]}' | \
jq -r '.secret')
@@ -77,7 +77,7 @@ talos keys batch-verify "$KEY1" "$KEY2" "invalid-key-for-testing" \
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:batchVerify" \
-H "Content-Type: application/json" \
-d "{
\"requests\": [
@@ -91,15 +91,14 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
-The current `talos keys batch-verify` CLI command uses the admin-scoped batch verify API under the hood. The curl example above
-shows the self-service data-plane endpoint.
-
### Response format
The response contains a `results` array. Each element has the same fields as a single
-[verify response](./issue-and-verify.md#verification-response). Results are returned in the same order as the requests.
+[verify response](./issue-and-verify.md#verification-response). Results are returned in the same
+order as the requests.
-Invalid credentials return `active: false` with an `error_code` — they do not cause the batch request to fail.
+Invalid credentials return `active: false` with an `error_code` — they do not cause the batch
+request to fail.
### Limits
@@ -131,7 +130,7 @@ JSON
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
-H "Content-Type: application/json" \
-d '{
"requests": [
@@ -147,12 +146,13 @@ curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
### Response format
-The response includes a `results` array with per-item outcomes, plus `success_count` and `failure_count` counters. The HTTP
-response is `200 OK` if at least one key succeeds. Check `failure_count` and individual `error_code` fields to detect partial
-failures.
+The response includes a `results` array with per-item outcomes, plus `success_count` and
+`failure_count` counters. The HTTP response is `200 OK` if at least one key succeeds. Check
+`failure_count` and individual `error_code` fields to detect partial failures.
For the complete field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch
+import error codes, see the
[error codes reference](../reference/error-codes.md#batch-import-error-codes).
### Limits
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.md
index 4db8a03217..6780175274 100644
--- a/docs/talos/integrate/derive-tokens.md
+++ b/docs/talos/integrate/derive-tokens.md
@@ -7,13 +7,15 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Derive tokens
-Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived tokens when you need:
+Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived
+tokens when you need:
- **Browser-safe credentials** — JWTs can be verified client-side without hitting the server.
- **Temporary access** — grant time-limited access with a subset of the parent key's scopes.
- **Custom claims** — embed application-specific data in the token.
-Derived tokens inherit permissions from the parent API key and can be verified on the same data plane endpoint.
+Derived tokens inherit permissions from the parent API key and can be verified on the same data
+plane endpoint.
@@ -42,7 +44,7 @@ echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
```bash
-ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"derive-test","actor_id":"user_1","scopes":["read","write"]}')
@@ -82,7 +84,7 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$API_SECRET\",
@@ -103,17 +105,19 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or `TOKEN_ALGORITHM_MACAROON`),
-optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For the complete field reference, see the
+The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or
+`TOKEN_ALGORITHM_MACAROON`), optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For
+the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
-For HTTP API requests, `ttl` accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo` in addition to
-standard Go durations. The current CLI `--ttl` flag still expects standard Go durations such as `1h` or `30m`.
+For HTTP API requests, `ttl` accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds
+like `1y6mo` in addition to standard Go durations. The current CLI `--ttl` flag still expects
+standard Go durations such as `1h` or `30m`.
### Response
-The response contains a `token` object with `token.token` (the derived token string), `token.expire_time`, `token.scopes`, and
-`token.claims`. For the complete field reference, see the
+The response contains a `token` object with `token.token` (the derived token string),
+`token.expire_time`, `token.scopes`, and `token.claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
## Verify a derived token
@@ -133,7 +137,7 @@ talos keys verify "$JWT_TOKEN" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$JWT_TOKEN\"}" | jq .
```
@@ -141,9 +145,6 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-The current `talos keys verify` CLI command uses the admin-scoped verify API under the hood. The curl example above shows the
-self-service data-plane endpoint.
-
The verification response includes the token's scopes, actor, and metadata from the parent key.
## Derive a macaroon
@@ -166,7 +167,7 @@ talos keys derive-token "$API_SECRET" \
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$API_SECRET\",
@@ -189,7 +190,8 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
## JWKS endpoint
-For client-side JWT verification, fetch the public keys from the JWKS endpoint:
+For client-side JWT verification, fetch the public keys from the JWKS endpoint at
+`/v2alpha1/admin/derivedKeys/jwks.json`:
@@ -204,20 +206,43 @@ talos jwk get -e "$TALOS_URL"
```bash
-curl -s "$TALOS_URL/v2/admin/.well-known/jwks.json" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/derivedKeys/jwks.json" | jq .
```
-Configure your JWT library to fetch keys from this URL. The keys are loaded from the server's JWKS configuration and are typically
-cached.
+The endpoint serves the active public signing keys plus any retired keys still inside the
+verification window. Each entry includes a `kid` field that matches the `kid` header on tokens
+signed with that key.
+
+### Client-side caching and refresh
+
+Cache the JWKS response on the client so verification does not call Talos on every request.
+Recommended settings:
+
+| Setting | Recommended value | Notes |
+| -------------------- | ----------------- | ------------------------------------------------------- |
+| Cache TTL | 5 – 15 minutes | Bounds how long a rotated-out key keeps verifying. |
+| Refresh-on-miss | Enabled | If a token's `kid` is unknown, refetch JWKS once. |
+| Refresh failure mode | Serve stale | If the refetch fails, keep the previous keys until TTL. |
+
+Most mature JWT libraries (`jose` for Node, `PyJWT`/`PyJWKClient` for Python, `go-jose`,
+`jjwt` for Java) support these patterns natively — set the cache TTL and enable
+refresh-on-unknown-kid. Do not poll the endpoint on a fixed interval shorter than 1 minute; it adds
+load without changing the practical revocation window, which is bounded by the longest issued
+token TTL.
+
+When you rotate signing keys, keep the previous key in the JWKS response (mark it retired in the
+server config, do not delete the JWK) for at least the longest issued token TTL plus the maximum
+client cache TTL. Otherwise clients with a freshly cached JWKS that lacks the new `kid` can reject
+valid tokens until their cache expires.
## Scope restrictions
-Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any scope that the parent key
-does not have, the request fails with a `403 Forbidden` error. To restrict scopes, request only scopes that exist on the parent
-key.
+Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any
+scope that the parent key does not have, the request fails with a `403 Forbidden` error. To restrict
+scopes, request only scopes that exist on the parent key.
## Next steps
diff --git a/docs/talos/integrate/error-handling.md b/docs/talos/integrate/error-handling.md
index 2176483c75..b41d588fcb 100644
--- a/docs/talos/integrate/error-handling.md
+++ b/docs/talos/integrate/error-handling.md
@@ -7,38 +7,57 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Error handling
-All Talos API errors follow a consistent JSON format. This guide covers the error response structure, common error codes, and
-retry strategies.
+All Talos API errors follow the [google.rpc.Status](https://cloud.google.com/apis/design/errors#error_model)
+shape. This guide covers the error response structure, common error codes, and retry strategies.
## Error response format
-Error responses use this structure:
+Every non-2xx response uses the `google.rpc.Status` envelope:
```json
{
- "error": {
- "code": 400,
- "status": "Bad Request",
- "message": "The API key format is invalid.",
- "reason": "invalid_api_key_format"
- }
+ "code": 5,
+ "message": "API key not found",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "reason": "API_KEY_NOT_FOUND",
+ "domain": "talos.ory.sh",
+ "metadata": {
+ "key_id": "01J9X7…"
+ }
+ }
+ ]
}
```
-| Field | Description |
-| --------------- | --------------------------------- |
-| `error.code` | HTTP status code |
-| `error.status` | HTTP status text |
-| `error.message` | Human-readable error description |
-| `error.reason` | Machine-readable error identifier |
+| Field | Description |
+| --------- | ------------------------------------------------------------------------------------------------------ |
+| `code` | Canonical [gRPC status code](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) (integer 0-16). |
+| `message` | Human-readable summary. Suitable for logging, not for end-user display. |
+| `details` | Optional list of typed error details. `ErrorInfo` carries the machine-readable `reason`. |
+
+The HTTP status code is set from the canonical
+[gRPC-to-HTTP mapping](https://cloud.google.com/apis/design/errors#http_mapping). For example, code
+`5` (`NOT_FOUND`) returns HTTP 404; code `7` (`PERMISSION_DENIED`) returns HTTP 403.
+
+### Reading the reason
+
+The stable, machine-readable identifier is `details[*].reason` on the `ErrorInfo` detail. Match on
+`reason` — never on `message`, which can change between releases.
+
+```bash
+REASON=$(echo "$RESPONSE" | jq -r '.details[]? | select(."@type" | endswith("ErrorInfo")).reason')
+```
## Verification errors
-The verify endpoints (`POST /v2/apiKeys:verify` and `POST /v2/admin/apiKeys:verify`) return errors differently from most admin
-endpoints. Instead of an HTTP error, they return `200 OK` with `is_active: false` and a structured error code:
+The verify endpoint (`POST /v2alpha1/admin/apiKeys:verify`) is the one exception. A verification
+failure is part of the normal verification result, not a transport-level error, so it returns
+`200 OK` with `is_active: false` and a structured error code:
```json
{
@@ -48,12 +67,17 @@ endpoints. Instead of an HTTP error, they return `200 OK` with `is_active: false
}
```
+Treat the response as successful; act on `is_active` and `error_code`. Only fall back to the
+`google.rpc.Status` handling above when the HTTP status is not 2xx (for example, the verify request
+itself was malformed).
+
For the complete list of verification error codes (`VERIFICATION_ERROR_*`), see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
## HTTP status codes
-For the complete list of HTTP status codes and error IDs, see the [error codes reference](../reference/error-codes.md).
+For the complete list of HTTP status codes and reasons, see the
+[error codes reference](../reference/error-codes.md).
Key categories:
@@ -64,19 +88,22 @@ Key categories:
### Safe to retry
-- **503 Service Unavailable** — the server is temporarily overloaded. Retry with exponential backoff.
-- **504 Gateway Timeout** — the request timed out. Retry with backoff.
+- **`UNAVAILABLE` (HTTP 503)** — the server is temporarily overloaded. Retry with exponential
+ backoff.
+- **`DEADLINE_EXCEEDED` (HTTP 504)** — the request timed out. Retry with backoff.
- **Network errors** — connection refused, DNS failure, etc. Retry with backoff.
-### Not safe to retry (without idempotency key)
+### Not safe to retry without an idempotency key
-- **409 Conflict** — the resource already exists. Check the response and adjust.
-- **400 Bad Request** — fix the request before retrying.
+- **`ALREADY_EXISTS` (HTTP 409)** — the resource already exists. Read the existing resource and
+ reconcile.
+- **`INVALID_ARGUMENT` (HTTP 400)** / **`FAILED_PRECONDITION` (HTTP 400)** — fix the request before
+ retrying.
### Idempotency key
-When issuing API keys, you can include a `request_id` in the request body. This field is stored with the key for client-side
-deduplication:
+When issuing API keys, include `request_id` in the request body. This field is stored on the key
+for client-side deduplication:
@@ -92,7 +119,7 @@ talos keys issue "my-service" --actor user_1 -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "my-service",
@@ -104,8 +131,8 @@ curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
-The `request_id` is recorded in the key's metadata. The server does not enforce server-side idempotent replay (sending the same
-`request_id` twice creates two keys).
+The `request_id` is recorded in the key's metadata. The server does not enforce server-side
+idempotent replay — sending the same `request_id` twice creates two keys.
## Recommended backoff
@@ -117,7 +144,7 @@ attempt 4: wait 800ms
attempt 5: wait 1600ms (give up after this)
```
-Add jitter (random 0-50% of the wait time) to avoid thundering herd effects.
+Add jitter (random 0-50% of the wait time) to avoid thundering-herd effects.
## Next steps
diff --git a/docs/talos/integrate/import-keys.md b/docs/talos/integrate/import-keys.md
index 064a84a73c..d5448ea7e6 100644
--- a/docs/talos/integrate/import-keys.md
+++ b/docs/talos/integrate/import-keys.md
@@ -7,17 +7,19 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Import existing keys
-Talos can manage API keys that were created outside the system. Import lets you migrate from a legacy key management solution or
-centralize keys from multiple providers without rotating credentials. For large migrations, use the batchImport API to import up
-to 1000 keys in a single request.
+Talos can manage API keys that were created outside the system. Import lets you migrate from a
+legacy key management solution or centralize keys from multiple providers without rotating
+credentials. For large migrations, use the batchImport API to import up to 1000 keys in a single
+request.
## How import works
-When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original key is never stored.
-Verification works by computing the same hash and looking it up in the database.
+When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original
+key is never stored. Verification works by computing the same hash and looking it up in the
+database.
-Imported keys support the same features as issued keys: scopes, metadata, expiration, token derivation (JWT/macaroon), and
-revocation.
+Imported keys support the same features as issued keys: scopes, metadata, expiration, token
+derivation (JWT/macaroon), and revocation.
@@ -49,7 +51,7 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"raw_key": "sk_live_test_51OxAM2Qly",
@@ -71,14 +73,16 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`, `ttl`, and `metadata`. For
-the complete field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`,
+`ttl`, and `metadata`. For the complete field reference, see the
+[ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
The response returns an `imported_api_key` object. The `raw_key` is **never returned** after import.
## Verify an imported key
-Imported keys use the same verification endpoint as issued keys. The data plane automatically detects the credential type:
+Imported keys use the same verification endpoint as issued keys. The data plane automatically
+detects the credential type:
@@ -93,7 +97,7 @@ talos keys verify "sk_live_test_51OxAM2Qly" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d '{"credential":"sk_live_test_51OxAM2Qly"}' | jq .
```
@@ -123,7 +127,7 @@ JSON
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
-H "Content-Type: application/json" \
-d '{
"requests": [
@@ -138,11 +142,13 @@ curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
### Batch response
-The response includes a `results` array with per-item outcomes (`imported_api_key` on success, `error_code` and `error_message` on
-failure), plus `success_count` and `failure_count` counters. If at least one key succeeds, the HTTP response is `200 OK`.
+The response includes a `results` array with per-item outcomes (`imported_api_key` on success,
+`error_code` and `error_message` on failure), plus `success_count` and `failure_count` counters. If
+at least one key succeeds, the HTTP response is `200 OK`.
For the complete response field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch
+import error codes, see the
[error codes reference](../reference/error-codes.md#batch-import-error-codes).
## List imported keys
@@ -160,7 +166,7 @@ talos keys imported list -e "$TALOS_URL"
```bash
-curl -s "$TALOS_URL/v2/admin/importedApiKeys?actor_id=payment-service&page_size=10" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/importedApiKeys?actor_id=payment-service&page_size=10" | jq .
```
@@ -183,7 +189,7 @@ talos keys revoke "$IMPORTED_KEY_ID" --reason superseded -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/$IMPORTED_KEY_ID:revoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys/$IMPORTED_KEY_ID:revoke" \
-H "Content-Type: application/json" \
-d '{"reason": "REVOCATION_REASON_SUPERSEDED"}'
echo ""
@@ -210,7 +216,7 @@ talos keys imported delete "$IMPORTED_KEY_ID" -e "$TALOS_URL"
```bash
-curl -s -X DELETE "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID"
+curl -s -X DELETE "$TALOS_URL/v2alpha1/admin/importedApiKeys/$IMPORTED_KEY_ID"
echo ""
echo "Imported key deleted"
```
@@ -218,7 +224,11 @@ echo "Imported key deleted"
-:::caution Delete is permanent and irreversible. Prefer revocation for audit trail. :::
+:::caution
+
+Delete is permanent and irreversible. Prefer revocation for audit trail.
+
+:::
## Next steps
diff --git a/docs/talos/integrate/index.md b/docs/talos/integrate/index.md
index 4643473774..c967589137 100644
--- a/docs/talos/integrate/index.md
+++ b/docs/talos/integrate/index.md
@@ -5,37 +5,75 @@ description: Add API key authentication to your application
# Integrate Ory Talos
-Ory Talos exposes two HTTP APIs that map to distinct responsibilities:
+Ory Talos exposes two logical planes that map to distinct responsibilities:
-- **Admin plane** (`/v2/admin/...`) — Create, update, rotate, and revoke API keys. Deploy behind your internal network or VPN.
-- **Data plane** (`/v2/apiKeys:...`) — Verify credentials at the edge. Designed for sub-millisecond latency with caching enabled.
+- **Admin plane** — Create, update, rotate, and revoke API keys. Deploy behind your internal
+ network or VPN. All admin endpoints live under `/v2alpha1/admin/...`.
+- **Data plane** — Verify credentials with low latency and let key holders revoke their own keys.
+ The two public verification endpoints are `POST /v2alpha1/admin/apiKeys:verify` and
+ `POST /v2alpha1/admin/apiKeys:batchVerify`; the self-service endpoint is
+ `POST /v2alpha1/apiKeys:selfRevoke`.
-Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the data plane every time a request
-arrives.
+Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the
+data plane every time a request arrives.
+
+The verify endpoints share the `/admin/` URL prefix for historical reasons. They are still safe to
+expose publicly — they take a credential and return verification metadata only — but you must
+restrict the rest of `/admin/` at your edge. See
+[Exposing only the verify endpoints publicly](#exposing-only-the-verify-endpoints-publicly) below.
## Common workflows
-| Task | Endpoint | Guide |
-| --------------------------------------- | --------------------------------------------------------- | --------------------------------------- |
-| Issue a key and verify it | `POST /v2/admin/issuedApiKeys`, `POST /v2/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
-| Import keys from another system | `POST /v2/admin/importedApiKeys` | [Import keys](import-keys.md) |
-| Mint short-lived JWT or macaroon tokens | `POST /v2/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
-| Verify many credentials at once | `POST /v2/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
-| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
-| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
-| Let key holders revoke their own key | `POST /v2/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
-| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
+| Task | Endpoint | Guide |
+| --------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
+| Issue a key and verify it | `POST /v2alpha1/admin/issuedApiKeys`, `POST /v2alpha1/admin/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
+| Import keys from another system | `POST /v2alpha1/admin/importedApiKeys` | [Import keys](import-keys.md) |
+| Mint short-lived JWT or macaroon tokens | `POST /v2alpha1/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
+| Verify many credentials at once | `POST /v2alpha1/admin/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
+| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
+| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
+| Let key holders revoke their own key | `POST /v2alpha1/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
+| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
## Authentication
-The admin plane does not enforce authentication by default. Protect it at the infrastructure level (VPN, service mesh, reverse
-proxy with mTLS). The data plane is public-facing and requires no authentication — callers supply the credential they want to
-verify.
+The admin plane does not enforce authentication by default. Protect it at the infrastructure level
+(VPN, service mesh, reverse proxy with mTLS). The data plane is public-facing and requires no
+authentication — callers supply the credential they want to verify.
+
+## Exposing only the verify endpoints publicly
+
+Talos has no built-in admin authentication, so do not put `/v2alpha1/admin/*` on the public
+internet. Instead, run a reverse proxy (NGINX, Envoy, HAProxy, an API gateway) in front of the
+data-plane process and allow only the verify and self-revoke paths through:
+
+| Path | Method | Public | Reason |
+| -------------------------------------------- | ------ | ------ | ------------------------------------- |
+| `/v2alpha1/admin/apiKeys:verify` | POST | Yes | Verification — credential in request. |
+| `/v2alpha1/admin/apiKeys:batchVerify` | POST | Yes | Batch verification. |
+| `/v2alpha1/apiKeys:selfRevoke` | POST | Yes | Self-revocation by the key holder. |
+| `/health/alive`, `/health/ready` | GET | Maybe | Required for load-balancer probes. |
+| Everything else under `/v2alpha1/admin/...` | any | No | Issuance, rotation, admin revocation. |
+
+Example NGINX snippet that fronts the data plane:
+
+```nginx
+location = /v2alpha1/admin/apiKeys:verify { proxy_pass http://talos_data; }
+location = /v2alpha1/admin/apiKeys:batchVerify { proxy_pass http://talos_data; }
+location = /v2alpha1/apiKeys:selfRevoke { proxy_pass http://talos_data; }
+location = /health/alive { proxy_pass http://talos_data; }
+location = /health/ready { proxy_pass http://talos_data; }
+location / { return 404; }
+```
+
+Run the admin plane on a separate listener (or a separate process — see
+[Separate admin and data planes](../operate/deploy/separate-planes.md)) bound to an internal
+network so it cannot be reached even if the public proxy is misconfigured.
## Request format
-All endpoints accept and return JSON with `Content-Type: application/json`. Field names use `snake_case` (for example `actor_id`,
-`key_id`, `expire_time`).
+All endpoints accept and return JSON with `Content-Type: application/json`. Field names use
+`snake_case` (for example `actor_id`, `key_id`, `expire_time`).
Durations accept both Go format (`168h`, `30m`, `1h30m`) and protobuf format (`604800s`).
diff --git a/docs/talos/integrate/ip-restrictions.md b/docs/talos/integrate/ip-restrictions.md
index bf82d23317..63706c527a 100644
--- a/docs/talos/integrate/ip-restrictions.md
+++ b/docs/talos/integrate/ip-restrictions.md
@@ -7,8 +7,9 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# IP restrictions
-IP restrictions let you limit which client IPs can use an API key. When enabled, verification rejects requests from IPs outside
-the allowed CIDR ranges. Keys without IP restrictions are unrestricted.
+IP restrictions let you limit which client IPs can use an API key. When enabled, verification
+rejects requests from IPs outside the allowed CIDR ranges. Keys without IP restrictions are
+unrestricted.
## Prerequisites
@@ -19,8 +20,8 @@ A running Talos server. See the [quickstart](../quickstart/index.md) to start on
## Configure client IP source
-By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server runs behind a reverse proxy
-or CDN, configure the correct header in your Talos config:
+By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server
+runs behind a reverse proxy or CDN, configure the correct header in your Talos config:
```yaml
serve:
@@ -36,12 +37,13 @@ Supported values:
- `CLIENT_IP_SOURCE_X_REAL_IP` — Nginx
- `CLIENT_IP_SOURCE_TRUE_CLIENT_IP` — Cloudflare Enterprise
-This is a global setting — all IP restriction checks use the same source. Set it once to match your infrastructure topology.
+This is a global setting — all IP restriction checks use the same source. Set it once to match your
+infrastructure topology.
## Issue a key with IP restrictions
-Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both individual IPs (with `/32` or `/128`
-suffix) and CIDR ranges:
+Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both
+individual IPs (with `/32` or `/128` suffix) and CIDR ranges:
@@ -68,7 +70,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "restricted-key",
@@ -81,7 +83,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
@@ -90,7 +92,8 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
-For the complete request field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+For the complete request field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify from an allowed IP
@@ -109,7 +112,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\": \"$API_SECRET\"}")
@@ -123,8 +126,8 @@ The response includes the key metadata with `is_active: true`.
## Verification from a disallowed IP
-When the client IP is outside all allowed CIDR ranges, verification returns `VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does
-not reveal which CIDRs are configured.
+When the client IP is outside all allowed CIDR ranges, verification returns
+`VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does not reveal which CIDRs are configured.
For the full list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
@@ -148,7 +151,7 @@ talos keys issued update "$KEY_ID" \
```bash
-UPDATE_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+UPDATE_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"ip_restriction": {
@@ -179,7 +182,7 @@ talos keys issued update "$KEY_ID" \
```bash
-UNRESTRICT_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+UNRESTRICT_RESPONSE=$(curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"ip_restriction": {
@@ -217,7 +220,7 @@ talos keys imported import "imported-restricted" \
```bash
-IMPORT_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+IMPORT_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "imported-restricted",
@@ -234,16 +237,17 @@ echo "$IMPORT_RESPONSE" | jq .
-For the complete import field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+For the complete import field reference, see the
+[ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
## Behavior notes
-- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key is unrestricted (all IPs
- allowed).
+- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key
+ is unrestricted (all IPs allowed).
- **Cache TTL**: IP restriction changes take effect after the cache TTL expires. See
[cache configuration](../operate/cache/index.md) for TTL settings.
- **Fail-closed**: If client IP resolution fails, the request is denied.
-- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and `/128` for single IPv6
- addresses.
-- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens (JWTs/macaroons). Token verification
- checks the key's IP restrictions at derivation time.
+- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and
+ `/128` for single IPv6 addresses.
+- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens
+ (JWTs/macaroons). Token verification checks the key's IP restrictions at derivation time.
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.md
index 784aea38b3..34a19703fb 100644
--- a/docs/talos/integrate/issue-and-verify.md
+++ b/docs/talos/integrate/issue-and-verify.md
@@ -7,11 +7,13 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Issue and verify API keys
-This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are executable and tested in CI.
+This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are
+executable and tested in CI.
## Prerequisites
-A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start one locally.
+A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start
+one locally.
@@ -47,7 +49,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "backend-service",
@@ -71,22 +73,24 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`, `ttl`, `metadata`, and
-`rate_limit_policy`. For the complete field reference, see the
+The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`,
+`ttl`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
-For HTTP API requests, `ttl` also accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo`. The
-current CLI `--ttl` flag examples still use standard Go durations such as `720h` and `1h30m`.
+For HTTP API requests, `ttl` also accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and
+compounds like `1y6mo`. The current CLI `--ttl` flag examples still use standard Go durations such
+as `720h` and `1h30m`.
### Response fields
The response contains two top-level fields:
- **`issued_api_key`** — The key metadata (ID, name, actor, scopes, status, timestamps).
-- **`secret`** — The full API key credential. This value is returned **only once** and cannot be retrieved later. Store it
- securely.
+- **`secret`** — The full API key credential. This value is returned **only once** and cannot be
+ retrieved later. Store it securely.
-For the complete metadata field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+For the complete metadata field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a key
@@ -105,7 +109,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -113,29 +117,30 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
-The current `talos keys verify` CLI command uses the admin-scoped verify API under the hood. The curl example above shows the
-self-service data-plane endpoint that credential holders can call directly.
-
### Verification response
-The response includes `is_active` (boolean), `key_id`, `actor_id`, `issuer`, `scopes`, `metadata`, and `expire_time` when valid.
-When `is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled
-(Commercial), the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For
-the complete field reference, see the [VerifyAPIKey API reference](../reference/api/verify-api-key.api.mdx).
+The response includes `is_active` (boolean), `key_id`, `actor_id`, `issuer`, `scopes`, `metadata`,
+and `expire_time` when valid. When `is_active` is `false`, `error_code` and `error_message` indicate
+the reason. When rate limit enforcement is enabled (Commercial), the response also includes
+`rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the
+complete field reference, see the
+[VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
### Verification error codes
-When `is_active` is `false`, the `error_code` field indicates why. Common codes include `VERIFICATION_ERROR_EXPIRED`,
-`VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and `VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's
-rate limit quota is exhausted). For the complete list, see the
+When `is_active` is `false`, the `error_code` field indicates why. Common codes include
+`VERIFICATION_ERROR_EXPIRED`, `VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and
+`VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's rate limit quota is exhausted). For
+the complete list, see the
[verification error codes reference](../reference/error-codes.md#verification-error-codes).
## Cache bypass
-Verification results are cached for performance. After revoking a key, you can bypass the cache for immediate consistency:
+Verification results are cached for performance. After revoking a key, you can bypass the cache for
+immediate consistency:
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{"credential":"sk_..."}'
@@ -166,7 +171,7 @@ talos keys issued get "$KEY_ID" -e "$TALOS_URL"
```bash
-curl -s "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" | jq .
```
@@ -191,7 +196,7 @@ talos keys issued list --actor user_42 --page-size 10 -e "$TALOS_URL"
```bash
-curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
```
@@ -199,8 +204,9 @@ curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=10&actor_id=user_42" | jq .
### Query parameters
-Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status` (filtering). For the complete
-parameter reference, see the [ListIssuedAPIKeys API reference](../reference/api/admin-list-issued-api-keys.api.mdx).
+Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status`
+(filtering). For the complete parameter reference, see the
+[ListIssuedAPIKeys API reference](../reference/api/admin-list-issued-api-keys.api.mdx).
The response includes a `next_page_token` field. When empty, you have reached the last page.
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.md
index 01cc5c0a63..7ce8b266ae 100644
--- a/docs/talos/integrate/key-lifecycle.md
+++ b/docs/talos/integrate/key-lifecycle.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Key lifecycle
-After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All lifecycle operations use the admin
-plane.
+After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All
+lifecycle operations use the admin plane.
@@ -40,7 +40,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"lifecycle-test","actor_id":"user_1","scopes":["read","write"],"metadata":{"team":"backend"}}')
@@ -55,13 +55,15 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
-When you set `ttl` on issue or import requests, the HTTP API accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and
-compounds like `1y6mo` in addition to standard Go durations. The current CLI `--ttl` flags still expect standard Go duration
-strings; see the [configuration reference](../reference/config.md) for the canonical duration format summary.
+When you set `ttl` on issue or import requests, the HTTP API accepts extended formats such as `1y`,
+`1mo`, `1w`, `1d`, and compounds like `1y6mo` in addition to standard Go durations. The current CLI
+`--ttl` flags still expect standard Go duration strings; see the
+[configuration reference](../reference/config.md) for the canonical duration format summary.
## Update key metadata
-Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the secret:
+Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the
+secret:
@@ -80,7 +82,7 @@ talos keys issued update "$KEY_ID" \
```bash
-curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "lifecycle-test-updated",
@@ -95,10 +97,11 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
### Update mask
-The `update_mask` field controls which fields are modified. Only fields listed in `paths` are changed. This follows the
-[AIP-134](https://google.aip.dev/134) standard for partial updates.
+The `update_mask` field controls which fields are modified. Only fields listed in `paths` are
+changed. This follows the [AIP-134](https://google.aip.dev/134) standard for partial updates.
-Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
+Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete
+field reference, see the
[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Rotate a key
@@ -128,7 +131,7 @@ echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys/${KEY_ID}:rotate" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys/${KEY_ID}:rotate" \
-H "Content-Type: application/json" \
-d '{
"scopes": ["read", "write", "admin"],
@@ -148,22 +151,23 @@ echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Rotation response
-The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once), and `old_issued_api_key`
-(status `KEY_STATUS_REVOKED`). For the complete field reference, see the
+The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once),
+and `old_issued_api_key` (status `KEY_STATUS_REVOKED`). For the complete field reference, see the
[RotateIssuedAPIKey API reference](../reference/api/admin-rotate-issued-api-key.api.mdx).
### Zero-downtime rotation
The `:rotate` endpoint revokes the old key immediately. For zero-downtime rotation:
-1. Issue a new key with `POST /v2/admin/issuedApiKeys`
+1. Issue a new key with `POST /v2alpha1/admin/issuedApiKeys`
2. Deploy the new secret to all services
3. Verify the new secret works everywhere
-4. Revoke the old key with `POST /v2/admin/apiKeys/{old_key_id}:revoke`
+4. Revoke the old key with `POST /v2alpha1/admin/apiKeys/{old_key_id}:revoke`
## Revoke a key
-Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache TTL):
+Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache
+TTL):
@@ -178,7 +182,7 @@ talos keys revoke "$KEY_ID" --reason superseded -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys/${KEY_ID}:revoke" \
-H "Content-Type: application/json" \
-d '{"reason": "REVOCATION_REASON_SUPERSEDED"}'
echo ""
@@ -191,16 +195,18 @@ echo "Key revoked"
### Revocation reasons
Standard reasons include `REVOCATION_REASON_KEY_COMPROMISE`, `REVOCATION_REASON_SUPERSEDED`,
-`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only). For the complete list, see the
+`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only).
+For the complete list, see the
[RevokeAPIKey API reference](../reference/api/admin-revoke-api-key.api.mdx).
-When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable explanation.
+When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable
+explanation.
### Revocation and caching
-Revocation takes effect in the database immediately. However, if caching is enabled, previously cached verification results may
-remain valid until the cache entry expires. To force immediate effect, use the `Cache-Control: no-cache` header on verification
-requests.
+Revocation takes effect in the database immediately. However, if caching is enabled, previously
+cached verification results may remain valid until the cache entry expires. To force immediate
+effect, use the `Cache-Control: no-cache` header on verification requests.
## Verify after revocation
@@ -219,7 +225,7 @@ talos keys verify "$API_SECRET" --no-cache -e "$TALOS_URL" || true
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
diff --git a/docs/talos/integrate/rate-limiting.md b/docs/talos/integrate/rate-limiting.md
index fe2a8c979d..fa2a28b9db 100644
--- a/docs/talos/integrate/rate-limiting.md
+++ b/docs/talos/integrate/rate-limiting.md
@@ -7,21 +7,23 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Rate limiting
-Rate limit policies let you cap how many verification requests a key can serve within a time window. Talos stores the policy on
-the key, returns it in verification responses, and -- in the Commercial edition -- enforces it server-side. For background on how
-enforcement works in each edition, see the [rate limiting concepts page](../concepts/rate-limiting.md).
+Rate limit policies let you cap how many verification requests a key can serve within a time window.
+Talos stores the policy on the key, returns it in verification responses, and -- in the Commercial
+edition -- enforces it server-side. For background on how enforcement works in each edition, see the
+[rate limiting concepts page](../concepts/rate-limiting.md).
## Prerequisites
-A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to start one locally.
+A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to
+start one locally.
## Attach a rate limit policy
-Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a `window` (time window as a
-duration string, e.g. `"60s"`):
+Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a
+`window` (time window as a duration string, e.g. `"60s"`):
@@ -47,7 +49,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "rate-limited-key",
@@ -70,12 +72,14 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
-The response includes the full key metadata with the `rate_limit_policy` attached. For the complete request and response field
-reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+The response includes the full key metadata with the `rate_limit_policy` attached. For the complete
+request and response field reference, see the
+[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a rate-limited key
-Verify the key as you would any other credential. When the key has a rate limit policy, the response includes the policy metadata:
+Verify the key as you would any other credential. When the key has a rate limit policy, the response
+includes the policy metadata:
@@ -88,7 +92,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -96,14 +100,16 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
-When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining` (approximate requests available
-before the limit is reached) and `rate_limit_reset_time` (when full capacity is recovered). For the complete response field
-reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining`
+(approximate requests available before the limit is reached) and `rate_limit_reset_time` (when full
+capacity is recovered). For the complete response field reference, see the
+[VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
## Exceeding the limit
-When a key's quota is exhausted, verification returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`
-(Commercial edition). The response body includes the error code and a human-readable message:
+When a key's quota is exhausted, verification returns `is_active: false` with error code
+`VERIFICATION_ERROR_RATE_LIMITED` (Commercial edition). The response body includes the error code
+and a human-readable message:
```json
{
@@ -113,15 +119,17 @@ When a key's quota is exhausted, verification returns `is_active: false` with er
}
```
-The HTTP response also includes a `Retry-After` header indicating how many seconds the client should wait before retrying. In the
-OSS edition, enforcement is external -- Talos always returns the policy metadata but does not reject requests based on quota.
+The HTTP response also includes a `Retry-After` header indicating how many seconds the client should
+wait before retrying. In the OSS edition, enforcement is external -- Talos always returns the policy
+metadata but does not reject requests based on quota.
For the complete list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
## Update rate limit policy
-Use `PATCH` to change a key's rate limit policy without rotating the secret. Include `rate_limit_policy` in the `update_mask`:
+Use `PATCH` to change a key's rate limit policy without rotating the secret. Include
+`rate_limit_policy` in the `update_mask`:
@@ -137,7 +145,7 @@ talos keys issued update "$KEY_ID" \
```bash
-curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"rate_limit_policy": {
@@ -151,8 +159,9 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
-The updated policy takes effect on the next verification request (subject to cache TTL). For the complete update field reference,
-see the [UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
+The updated policy takes effect on the next verification request (subject to cache TTL). For the
+complete update field reference, see the
+[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Remove rate limit policy
@@ -172,7 +181,7 @@ talos keys issued update "$KEY_ID" \
```bash
-curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"rate_limit_policy": {},
@@ -187,7 +196,8 @@ Once removed, the key is no longer subject to rate limiting.
## HTTP response headers
-When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in verification responses:
+When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in
+verification responses:
| Header | When present | Description |
| ------------------ | -------------------- | -------------------------------------------------- |
@@ -195,22 +205,25 @@ When a key has a rate limit policy, the HTTP gateway includes IETF draft-complia
| `RateLimit` | Always (with policy) | Current state: `limit=100, remaining=42, reset=18` |
| `Retry-After` | Only when limited | Seconds to wait before the next allowed request |
-These headers are present in both editions. In the OSS edition, your API gateway can read them to apply enforcement. In the
-Commercial edition, clients can use them for backoff and retry logic.
+These headers are present in both editions. In the OSS edition, your API gateway can read them to
+apply enforcement. In the Commercial edition, clients can use them for backoff and retry logic.
## Behavior notes
-- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is down), verification succeeds but
- rate limit metadata is omitted. Limiter failures never block legitimate traffic.
-- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result is served from cache, the
- rate limiter is not consulted. This means cached responses do not decrement the counter.
-- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets, even if they belong to the
- same actor.
-- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate effect, use the
- `Cache-Control: no-cache` header on verification requests.
+- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is
+ down), verification succeeds but rate limit metadata is omitted. Limiter failures never block
+ legitimate traffic.
+- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result
+ is served from cache, the rate limiter is not consulted. This means cached responses do not
+ decrement the counter.
+- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets,
+ even if they belong to the same actor.
+- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate
+ effect, use the `Cache-Control: no-cache` header on verification requests.
## Next steps
-- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs. Commercial
+- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs.
+ Commercial
- [Key lifecycle](./key-lifecycle.md) -- update, rotate, and revoke keys
- [Error handling](./error-handling.md) -- error response format and retry logic
diff --git a/docs/talos/integrate/sdk/curl.md b/docs/talos/integrate/sdk/curl.md
index f55fe58946..8501ecd8d4 100644
--- a/docs/talos/integrate/sdk/curl.md
+++ b/docs/talos/integrate/sdk/curl.md
@@ -17,7 +17,7 @@ Replace `$TALOS_URL` with your Talos server address (e.g., `http://127.0.0.1:442
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "my-service",
@@ -30,7 +30,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
@@ -41,7 +41,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-curl -s "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" | jq .
```
### List keys
@@ -49,7 +49,7 @@ curl -s "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" | jq .
```bash
-curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=50&actor_id=user_123&status=KEY_STATUS_ACTIVE" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/issuedApiKeys?page_size=50&actor_id=user_123&status=KEY_STATUS_ACTIVE" | jq .
```
### Update a key
@@ -57,7 +57,7 @@ curl -s "$TALOS_URL/v2/admin/issuedApiKeys?page_size=50&actor_id=user_123&status
```bash
-curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
+curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "updated-name",
@@ -71,7 +71,7 @@ curl -s -X PATCH "$TALOS_URL/v2/admin/issuedApiKeys/$KEY_ID" \
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys/${KEY_ID}:rotate" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys/${KEY_ID}:rotate" \
-H "Content-Type: application/json" \
-d '{}')
@@ -88,7 +88,7 @@ echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"raw_key": "sk_live_abc123",
@@ -99,7 +99,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
```
@@ -108,7 +108,7 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
-H "Content-Type: application/json" \
-d '{
"requests": [
@@ -123,7 +123,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys:batchImport" \
```bash
-curl -s "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
```
### List imported keys
@@ -131,7 +131,7 @@ curl -s "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
```bash
-curl -s "$TALOS_URL/v2/admin/importedApiKeys?page_size=50&actor_id=user_123" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/importedApiKeys?page_size=50&actor_id=user_123" | jq .
```
### Delete an imported key
@@ -139,7 +139,7 @@ curl -s "$TALOS_URL/v2/admin/importedApiKeys?page_size=50&actor_id=user_123" | j
```bash
-curl -s -X DELETE "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
+curl -s -X DELETE "$TALOS_URL/v2alpha1/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
```
## Admin plane — Token derivation
@@ -149,7 +149,7 @@ curl -s -X DELETE "$TALOS_URL/v2/admin/importedApiKeys/$IMPORTED_KEY_ID" | jq .
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$API_SECRET\",
@@ -170,7 +170,7 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$API_SECRET\",
@@ -184,7 +184,7 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
```bash
-curl -s "$TALOS_URL/v2/admin/.well-known/jwks.json" | jq .
+curl -s "$TALOS_URL/v2alpha1/admin/derivedKeys/jwks.json" | jq .
```
## Data plane
@@ -194,7 +194,7 @@ curl -s "$TALOS_URL/v2/admin/.well-known/jwks.json" | jq .
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -204,7 +204,7 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
@@ -215,7 +215,7 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:batchVerify" \
-H "Content-Type: application/json" \
-d "{
\"requests\": [
@@ -232,7 +232,7 @@ curl -s -X POST "$TALOS_URL/v2/apiKeys:batchVerify" \
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys/${KEY_ID}:revoke" \
-H "Content-Type: application/json" \
-d '{"reason": "REVOCATION_REASON_KEY_COMPROMISE"}' | jq .
```
@@ -243,13 +243,13 @@ curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
```bash
# Issue a fresh key for the self-revocation demo
-SELF_REVOKE_RESP=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+SELF_REVOKE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"self-revoke-demo","actor_id":"user_123"}')
SELF_REVOKE_SECRET=$(echo "$SELF_REVOKE_RESP" | jq -r '.secret')
-curl -s -X POST "$TALOS_URL/v2/apiKeys:selfRevoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/apiKeys:selfRevoke" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$SELF_REVOKE_SECRET\",
diff --git a/docs/talos/integrate/sdk/go.md b/docs/talos/integrate/sdk/go.md
index b98ca84dbf..12802a7180 100644
--- a/docs/talos/integrate/sdk/go.md
+++ b/docs/talos/integrate/sdk/go.md
@@ -5,12 +5,17 @@ description: Using the generated Go HTTP client
# Go SDK
-Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is generated using `openapi-generator`
-and lives in the `internal/client/generated` package.
+Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is
+generated using `openapi-generator` and lives in the `internal/client/generated` package.
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. It is used for
-Talos's own integration tests and the admin UI backend. If you need a Go client for your application, generate one from the
-OpenAPI spec at `api/talos.openapi-v2.json` using [OpenAPI Generator](https://openapi-generator.tech/). :::
+:::note
+
+Internal package: the Go client is in an `internal/` package and cannot be imported by external Go
+modules. It is used for Talos's own integration tests and the admin UI backend. If you need a Go
+client for your application, generate one from the OpenAPI spec at `api/talos.openapi-v2.json`
+using [OpenAPI Generator](https://openapi-generator.tech/).
+
+:::
@@ -24,11 +29,16 @@ openapi-generator generate \
-o generated/go-client
```
-The examples below use the internal client's types for illustration. A generated external client has the same API shape.
+The examples below use the internal client's types for illustration. A generated external client has
+the same API shape.
+
+:::tip
-:::tip Full working example See
-[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go) for a
-complete, runnable program that exercises all operations shown below. :::
+Full working example: see
+[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go)
+for a complete, runnable program that exercises all operations shown below.
+
+:::
@@ -56,7 +66,7 @@ c := client.NewAPIClient(cfg)
```go
issueResp, _, err := c.StaticCredentialsAPI.
AdminIssueAPIKey(ctx).
- V2IssueAPIKeyRequest(client.V2IssueAPIKeyRequest{
+ V2alpha1IssueAPIKeyRequest(client.V2alpha1IssueAPIKeyRequest{
Name: new("my-service"),
ActorId: new("user_123"),
Scopes: []string{"read", "write"},
@@ -80,7 +90,7 @@ fmt.Println("Secret:", issueResp.GetSecret())
```go
verifyResp, _, err := c.StaticCredentialsAPI.
AdminVerifyAPIKey(ctx).
- V2VerifyAPIKeyRequest(client.V2VerifyAPIKeyRequest{
+ V2alpha1VerifyAPIKeyRequest(client.V2alpha1VerifyAPIKeyRequest{
Credential: new(secret),
}).
Execute()
@@ -102,8 +112,8 @@ if verifyResp.GetIsActive() {
```go
batchResp, _, err := c.StaticCredentialsAPI.
AdminBatchVerifyAPIKeys(ctx).
- V2BatchVerifyAPIKeysRequest(client.V2BatchVerifyAPIKeysRequest{
- Requests: []client.V2VerifyAPIKeyRequest{
+ V2alpha1BatchVerifyAPIKeysRequest(client.V2alpha1BatchVerifyAPIKeysRequest{
+ Requests: []client.V2alpha1VerifyAPIKeyRequest{
{Credential: new(secret)},
{Credential: new("invalid-key-for-testing")},
},
@@ -125,7 +135,7 @@ Enum fields use typed constants, not raw strings:
```go
-reason := client.V2REVOCATIONREASON_REVOCATION_REASON_KEY_COMPROMISE
+reason := client.V2ALPHA1REVOCATIONREASON_REVOCATION_REASON_KEY_COMPROMISE
_, _, err = c.StaticCredentialsAPI.
AdminRevokeAPIKey(ctx, keyID).
StaticCredentialsAdminRevokeAPIKeyBody(client.StaticCredentialsAdminRevokeAPIKeyBody{
@@ -143,10 +153,10 @@ fmt.Println("Key revoked successfully")
```go
-algorithm := client.V2TOKENALGORITHM_TOKEN_ALGORITHM_JWT
+algorithm := client.V2ALPHA1TOKENALGORITHM_TOKEN_ALGORITHM_JWT
deriveResp, _, err := c.StaticCredentialsAPI.
AdminDeriveToken(ctx).
- V2DeriveTokenRequest(client.V2DeriveTokenRequest{
+ V2alpha1DeriveTokenRequest(client.V2alpha1DeriveTokenRequest{
Credential: new(secret),
Algorithm: &algorithm,
Ttl: new("1h"),
@@ -163,7 +173,10 @@ fmt.Println("JWT:", derivedToken.GetToken())
## Error handling
-The SDK returns errors for non-2xx responses. Use the HTTP response to inspect error details:
+The SDK returns an error for every non-2xx response. The error wraps a
+[`google.rpc.Status`](https://cloud.google.com/apis/design/errors#error_model) body — read it via
+the typed `GenericOpenAPIError`, not the HTTP response, so you get the canonical gRPC code,
+human-readable message, and any `ErrorInfo` details.
@@ -172,12 +185,39 @@ _, httpResp, err := c.StaticCredentialsAPI.
AdminGetIssuedAPIKey(ctx, "nonexistent-id").
Execute()
if err != nil {
- if httpResp != nil {
- fmt.Println("HTTP status:", httpResp.StatusCode)
+ var apiErr *client.GenericOpenAPIError
+ if errors.As(err, &apiErr) {
+ var status struct {
+ Code int32 `json:"code"`
+ Message string `json:"message"`
+ Details []struct {
+ Type string `json:"@type"`
+ Reason string `json:"reason"`
+ Domain string `json:"domain"`
+ Metadata map[string]string `json:"metadata"`
+ } `json:"details"`
+ }
+ if jsonErr := json.Unmarshal(apiErr.Body(), &status); jsonErr == nil {
+ fmt.Println("gRPC code:", status.Code) // 5 = NOT_FOUND
+ fmt.Println("HTTP status:", httpResp.StatusCode) // 404
+ fmt.Println("Message:", status.Message)
+ for _, d := range status.Details {
+ if strings.HasSuffix(d.Type, "ErrorInfo") {
+ fmt.Println("Reason:", d.Reason) // Stable; switch on this
+ }
+ }
+ }
}
}
```
+Match on `details[*].reason` from the `ErrorInfo` detail — it is the stable, machine-readable
+identifier. The `message` field is meant for logs and can change between releases.
+
+For the verify endpoint, a verification failure returns `200 OK` with `is_active: false`, not an
+HTTP error. Branch on `verifyResp.GetIsActive()` and inspect `verifyResp.GetErrorCode()` instead of
+treating it as an SDK error.
+
## Regenerating the client
The Go SDK is regenerated with:
@@ -186,4 +226,5 @@ The Go SDK is regenerated with:
make generate-sdk
```
-This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to `internal/client/generated/`.
+This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to
+`internal/client/generated/`.
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.md
index 8cd127b4b4..69ae583f81 100644
--- a/docs/talos/integrate/self-revocation.md
+++ b/docs/talos/integrate/self-revocation.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Self-revocation
-The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the secret. This is a data plane
-operation — it does not require admin access.
+The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the
+secret. This is a data plane operation — it does not require admin access.
## Prerequisites
@@ -45,7 +45,7 @@ echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
```bash
-ISSUE_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+ISSUE_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "self-revoke-demo",
@@ -60,27 +60,6 @@ echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
-## Verify your own credential
-
-Use the data-plane verify endpoint when a credential holder needs to check a key without admin credentials. The admin-plane verify
-endpoint returns the same response shape and is still useful for operator workflows.
-
-
-
-
-
-
-```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
- -H "Content-Type: application/json" \
- -d "{\"credential\":\"$SELF_REVOKE_SECRET\"}" | jq .
-```
-
-
-
-
-For the complete response fields, see the [Verify API Key reference](../reference/api/verify-api-key.api.mdx).
-
Send the full key secret as proof of possession:
@@ -98,7 +77,7 @@ talos keys self-revoke "$SELF_REVOKE_SECRET" \
```bash
-curl -s -X POST "$TALOS_URL/v2/apiKeys:selfRevoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/apiKeys:selfRevoke" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$SELF_REVOKE_SECRET\",
@@ -127,7 +106,7 @@ echo "Self-revocation confirmed"
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$SELF_REVOKE_SECRET\"}")
@@ -145,20 +124,23 @@ fi
-The request requires `credential` (the full API key secret) and optionally `reason` (revocation reason enum). For the complete
-field reference, see the [SelfRevokeAPIKey API reference](../reference/api/revoke-api-key.api.mdx).
+The request requires `credential` (the full API key secret) and optionally `reason` (revocation
+reason enum). For the complete field reference, see the
+[SelfRevokeAPIKey API reference](../reference/api/revoke-api-key.api.mdx).
-Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are stateless and cannot be revoked.
-All revocation reasons except `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
+Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are
+stateless and cannot be revoked. All revocation reasons except
+`REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
revocations.
-A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is immediately revoked.
+A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is
+immediately revoked.
## Admin vs self-revocation
| | Admin revocation | Self-revocation |
| --------------------- | ---------------------------------------- | -------------------------------- |
-| Endpoint | `POST /v2/admin/apiKeys/{key_id}:revoke` | `POST /v2/apiKeys:selfRevoke` |
+| Endpoint | `POST /v2alpha1/admin/apiKeys/{key_id}:revoke` | `POST /v2alpha1/apiKeys:selfRevoke` |
| Plane | Admin | Data |
| Authentication | Requires admin access | Proof of possession (key secret) |
| Identifier | Key ID | Key secret |
diff --git a/docs/talos/operate/benchmarks.md b/docs/talos/operate/benchmarks.md
index ed8ee014ce..68470f42e7 100644
--- a/docs/talos/operate/benchmarks.md
+++ b/docs/talos/operate/benchmarks.md
@@ -5,20 +5,21 @@ description: Performance benchmarks and load testing for Ory Talos
# Benchmarks
-Talos includes a k6-based load test suite that measures throughput, latency, and correctness under concurrent load. Use these
-benchmarks to validate your deployment and catch performance regressions.
+Talos includes a k6-based load test suite that measures throughput, latency, and correctness under
+concurrent load. Use these benchmarks to validate your deployment and catch performance regressions.
:::note
-These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS edition uses SQLite, which
-does not support concurrent writers and cannot handle the parallel load generated by multi-VU test profiles.
+These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS
+edition uses SQLite, which does not support concurrent writers and cannot handle the parallel load
+generated by multi-VU test profiles.
:::
## Reference results
-Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress profile (ramping 0→437 VUs
-over 5 minutes):
+Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress
+profile (ramping 0→437 VUs over 5 minutes):
| Metric | Value |
| ------------------- | ------------ |
@@ -51,8 +52,8 @@ The stress profile ramps through four stages:
4. **Hold**: 150 VUs for 120s
5. **Ramp down**: 150→0 VUs over 30s
-Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write scenarios (create, rotate,
-revoke, import, update, self-revoke) get ~30%.
+Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write
+scenarios (create, rotate, revoke, import, update, self-revoke) get ~30%.
## Running benchmarks
@@ -75,8 +76,8 @@ TEST_PROFILE=load bash test/load/run.sh
TEST_PROFILE=stress bash test/load/run.sh
```
-The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker, runs migrations, seeds tenant
-data, starts the server, and executes k6.
+The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker,
+runs migrations, seeds tenant data, starts the server, and executes k6.
### Using an existing database
@@ -124,10 +125,12 @@ Each profile enforces regression thresholds. Tests fail if any threshold is brea
After a k6 run, look for:
- **`checks` rate**: Must be 100%. Any failure indicates a correctness bug.
-- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases suggest a regression.
+- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases
+ suggest a regression.
- **`http_req_failed` rate**: Should be 0% for smoke/load. Under 1% for stress.
-- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against the reference results to
- detect throughput regressions.
+- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against
+ the reference results to detect throughput regressions.
- **`iteration_duration`**: End-to-end time for each VU iteration including all operations.
-Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json` (machine-readable).
+Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json`
+(machine-readable).
diff --git a/docs/talos/operate/cache/index.md b/docs/talos/operate/cache/index.md
index 10760e2546..e5037c98be 100644
--- a/docs/talos/operate/cache/index.md
+++ b/docs/talos/operate/cache/index.md
@@ -24,8 +24,8 @@ cache:
## Consistency
-Caching introduces eventual consistency. A revoked key may continue to pass verification until the cache entry expires (default: 5
-minutes).
+Caching introduces eventual consistency. A revoked key may continue to pass verification until the
+cache entry expires (default: 5 minutes).
-**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for individual requests when
-immediate consistency is required.
+**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for
+individual requests when immediate consistency is required.
diff --git a/docs/talos/operate/cache/memory.md b/docs/talos/operate/cache/memory.md
index 1fba0276b4..2f08db13e9 100644
--- a/docs/talos/operate/cache/memory.md
+++ b/docs/talos/operate/cache/memory.md
@@ -7,7 +7,8 @@ sidebar_custom_props:
# In-memory cache
-The in-memory cache stores verification results in the Talos process using a ristretto-based LRU cache.
+The in-memory cache stores verification results in the Talos process using a ristretto-based LRU
+cache.
## Configuration
@@ -29,5 +30,6 @@ cache:
## When to use
-Use the in-memory cache for single-node deployments or when each Talos instance handles enough traffic to benefit from local
-caching. For multi-instance deployments, consider [Redis](redis.md) for shared cache across all instances.
+Use the in-memory cache for single-node deployments or when each Talos instance handles enough
+traffic to benefit from local caching. For multi-instance deployments, consider [Redis](redis.md)
+for shared cache across all instances.
diff --git a/docs/talos/operate/cache/redis.md b/docs/talos/operate/cache/redis.md
index cc24e1fa63..8779a8eba3 100644
--- a/docs/talos/operate/cache/redis.md
+++ b/docs/talos/operate/cache/redis.md
@@ -16,24 +16,77 @@ cache:
type: "redis"
ttl: "5m"
redis:
- addrs: ["redis:6379"]
+ addrs: ["redis-0:6379", "redis-1:6379", "redis-2:6379"]
password: "secret"
db: 0
pool_size: 100
+ min_idle_conns: 2
+ conn_max_idle_time: "5m"
+ conn_max_lifetime: "30m"
timeout: "3s"
+ tls:
+ enabled: true
```
## Parameters
-| Parameter | Default | Description |
-| ----------- | -------------------- | --------------------- |
-| `addrs` | `["localhost:6379"]` | Redis addresses |
-| `password` | — | Redis password |
-| `db` | `0` | Redis database number |
-| `pool_size` | `100` | Connection pool size |
-| `timeout` | `3s` | Operation timeout |
+| Parameter | Default | Range / format | Description |
+| -------------------- | -------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
+| `addrs` | `["localhost:6379"]` | One or more `host:port` entries | Redis server addresses. Multiple entries enable cluster or sentinel topologies. |
+| `password` | — | Any string | Redis password. Leave empty for unauthenticated Redis. |
+| `db` | `0` | `0`–`15` | Logical Redis database. Cluster mode only supports `0`. |
+| `pool_size` | `100` | `1`–`1000` | Maximum number of connections per address. |
+| `min_idle_conns` | `2` | `≥ 0` | Minimum idle connections kept open per address. Reduces cold-start latency. |
+| `conn_max_idle_time` | `5m` | Go duration string | Maximum time a connection can sit idle before being closed. |
+| `conn_max_lifetime` | `30m` | Go duration string | Maximum time a connection can be reused before being recycled. |
+| `timeout` | `3s` | Go duration string | Timeout for individual Redis operations (`GET`, `SET`, etc.). |
+| `tls.enabled` | `false` | Boolean | Enable TLS using the system certificate pool. Required for TLS-only Redis. |
+
+All Redis parameters are immutable: changing them requires a server restart. Only `pool_size` and
+`timeout` can be tuned without restart.
+
+## Cluster and sentinel topologies
+
+Pass every node in `addrs`. The client auto-detects the topology:
+
+```yaml
+# Redis Cluster (3+ nodes)
+addrs:
+ - "redis-cluster-0.svc:6379"
+ - "redis-cluster-1.svc:6379"
+ - "redis-cluster-2.svc:6379"
+
+# Redis Sentinel (3+ sentinels)
+addrs:
+ - "sentinel-0.svc:26379"
+ - "sentinel-1.svc:26379"
+ - "sentinel-2.svc:26379"
+```
+
+In cluster mode, `db` must be `0` — Redis Cluster does not support multiple logical databases.
+
+## TLS
+
+Set `tls.enabled: true` when the Redis endpoint terminates TLS. Talos uses the operating system's
+certificate pool to verify the server certificate. Self-signed or private CA deployments must add
+the CA to the OS trust store on every Talos node — there is no per-process CA bundle option.
+
+## Connection pool sizing
+
+The defaults (`pool_size: 100`, `min_idle_conns: 2`, `conn_max_lifetime: 30m`) suit most
+deployments. Tune them only when you can show a problem:
+
+- **Saturated pool:** if `redis_pool_wait_seconds` (when exposed by your client metrics) is
+ consistently non-zero, increase `pool_size`.
+- **Connection churn:** if Redis logs show frequent connect/disconnect from Talos, increase
+ `min_idle_conns`.
+- **Stale connections after failover:** lower `conn_max_lifetime` to force quicker rotation.
+
+Do not set `pool_size` above your Redis server's `maxclients` divided by the number of Talos
+instances — running out of Redis connections fails open with a cache miss but spams logs.
## When to use
-Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances, reducing database load. Redis
-is also required for [edge proxy](../deploy/edge-proxy.md) deployments where each edge node shares a regional Redis instance.
+Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances,
+reducing database load. Redis is also required for [edge proxy](../deploy/edge-proxy.md) deployments
+where each edge node shares a regional Redis instance.
diff --git a/docs/talos/operate/configure.md b/docs/talos/operate/configure.md
index dae9c923b0..ae59f7c090 100644
--- a/docs/talos/operate/configure.md
+++ b/docs/talos/operate/configure.md
@@ -5,13 +5,15 @@ description: Configuration reference for Ory Talos
# Configure
-Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set through environment variables
-or CLI flags. See the [Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
+Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set
+through environment variables or CLI flags. See the
+[Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
environment variable mappings, and precedence rules.
## Hot-reload
-Talos watches the config file for changes. Some settings reload automatically, others require a restart.
+Talos watches the config file for changes. Some settings reload automatically, others require a
+restart.
**Hot-reloadable:**
@@ -24,12 +26,30 @@ Talos watches the config file for changes. Some settings reload automatically, o
**Requires restart** (marked with `x-immutable` in the schema):
- `serve.http.host` / `port`
-- `serve.metrics.host` / `port`
+- `serve.metrics.host` / `port` (Commercial only)
- `db.dsn`
- `cache.type` and all cache settings
- `rate_limit.backend`
- `log.level` / `format`
-- `tracing.*`
+- `tracing.*` (Commercial only)
+
+## Duration syntax
+
+All duration values (TTLs, timeouts, intervals) are Go duration strings. Combine one or more
+unsigned numbers with a unit, no spaces. Supported units:
+
+| Unit | Meaning |
+| ---- | ------------ |
+| `ns` | nanoseconds |
+| `us` | microseconds |
+| `µs` | microseconds |
+| `ms` | milliseconds |
+| `s` | seconds |
+| `m` | minutes |
+| `h` | hours |
+
+Examples: `500ms`, `30s`, `5m`, `1h30m`, `8760h` (one year). Days, weeks, months, and years are
+**not** supported — express them in hours (`24h`, `168h`, `8760h`).
## Minimal configuration
@@ -55,7 +75,7 @@ serve:
allowed_origins: ["https://app.example.com"]
request_log:
exclude_health_endpoints: true
- metrics:
+ metrics: # Commercial only
host: "0.0.0.0"
port: 4422
@@ -71,8 +91,10 @@ credentials:
signing_key_id: "" # Optional JWKS kid hint; defaults to the first usable signing key
default_ttl: "1h"
signing_keys:
+ # Talos requires base64-encoded JWKS. To produce the value below, run:
+ # base64 < /etc/talos/jwks.json | tr -d '\n'
urls:
- - "file:///etc/talos/jwks.json"
+ - "base64://eyJrZXlzIjpbXX0="
db:
dsn: "postgres://talos:secret@db:5432/talos?max_conns=25&max_conn_lifetime=5m"
@@ -98,7 +120,7 @@ log:
level: "info"
format: "json"
-tracing:
+tracing: # Commercial only
enabled: true
service_name: "talos"
exporter: "otlp"
@@ -106,5 +128,5 @@ tracing:
sample_rate: 0.01
```
-See the [Configuration reference](../reference/config.md) for all available keys with types, defaults, and environment variable
-mappings.
+See the [Configuration reference](../reference/config.md) for all available keys with types,
+defaults, and environment variable mappings.
diff --git a/docs/talos/operate/database/cockroachdb.md b/docs/talos/operate/database/cockroachdb.md
index 9e8160f63e..18453ab751 100644
--- a/docs/talos/operate/database/cockroachdb.md
+++ b/docs/talos/operate/database/cockroachdb.md
@@ -32,20 +32,32 @@ export TALOS_DB_DSN="cockroach://talos@crdb:26257/talos?sslmode=verify-full&max_
cockroach://user:password@host:port/dbname?param=value¶m=value
```
-Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted to `postgres://` since
-CockroachDB uses the PostgreSQL wire protocol.
+Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted
+to `postgres://` since CockroachDB uses the PostgreSQL wire protocol.
## DSN parameters, connection pooling, and TLS
-CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including both standard and advanced pool
-modes. For the full parameter reference, see the [PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
-[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl) documentation.
+CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including
+both standard and advanced pool modes. For the full parameter reference, see the
+[PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
+[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl)
+documentation.
Key differences from PostgreSQL:
-- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of `25`.
-- **No connection limit pressure** — Each CockroachDB node independently manages connections, so total pool sizes can be larger
- without needing a connection pooler like PgBouncer.
+- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of
+ `25`.
+- **Per-node connection limits still apply** — each CockroachDB node enforces its own
+ `sql.defaults.idle_in_transaction_session_timeout` and accepts a finite number of connections.
+ Aim for the sum of every Talos pool that targets a node to stay below that node's limit. You
+ rarely need PgBouncer in front of CockroachDB, but the limit is per-node, not global.
+- **Schema-change blast radius** — CockroachDB applies online schema changes asynchronously.
+ Always run `talos migrate up` from a single instance, then wait for the schema-change job to
+ finish (`SHOW JOBS WHEN status = 'running'`) before starting a rolling deploy of the new
+ application version.
+- **Rollback path** — `talos migrate down` is supported but irreversible if the previous version
+ has already written data using the new schema. For destructive migrations, take a backup
+ (`BACKUP INTO …`) before applying.
## Migrations
@@ -55,8 +67,9 @@ talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
## Multi-region
-Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification latency. Talos does not require
-special configuration beyond pointing `db.dsn` at the local CockroachDB node.
+Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification
+latency. Talos does not require special configuration beyond pointing `db.dsn` at the local
+CockroachDB node.
```yaml
# Region: us-east-1
@@ -70,7 +83,8 @@ db:
## Performance
-CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For verification-heavy workloads:
+CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For
+verification-heavy workloads:
- Enable [caching](../cache/index.md) to absorb verification reads
- Use `max_conns=50` or higher — CockroachDB connections are lighter than PostgreSQL
diff --git a/docs/talos/operate/database/index.md b/docs/talos/operate/database/index.md
index 9c520783f8..163f881cc3 100644
--- a/docs/talos/operate/database/index.md
+++ b/docs/talos/operate/database/index.md
@@ -4,7 +4,8 @@ title: Database
# Database
-Talos stores API key data in a relational database. The backend is determined by the DSN scheme in `db.dsn`.
+Talos stores API key data in a relational database. The backend is determined by the DSN scheme in
+`db.dsn`.
## Supported backends
diff --git a/docs/talos/operate/database/migrations.md b/docs/talos/operate/database/migrations.md
index 7a00bd9624..8c6fbab193 100644
--- a/docs/talos/operate/database/migrations.md
+++ b/docs/talos/operate/database/migrations.md
@@ -12,20 +12,47 @@ Talos includes built-in database migrations. Run them before first use and after
# Apply all pending migrations
talos migrate up --database "sqlite:///var/lib/talos/data.db"
-# Roll back the last migration
+# Roll back the last migration (--steps defaults to 1)
talos migrate down --database "sqlite:///var/lib/talos/data.db"
+# Roll back the last three migrations
+talos migrate down --steps 3 --database "sqlite:///var/lib/talos/data.db"
+
# Check migration status
talos migrate status --database "sqlite:///var/lib/talos/data.db"
+
+# Force a specific version after a partial migration left the schema dirty
+talos migrate force 17 --database "sqlite:///var/lib/talos/data.db"
```
## Upgrade workflow
-1. Back up your database
-2. Stop the Talos server
-3. Run `talos migrate up`
-4. Verify with `talos migrate status`
-5. Start the new server binary
+1. **Back up the database.** For PostgreSQL or CockroachDB, take a logical backup with `pg_dump`
+ or `BACKUP INTO`; for MySQL, use `mysqldump`. SQLite users can simply copy the file.
+2. **Drain admin traffic.** Run `talos migrate up` from a single instance — concurrent migration
+ runners race against each other and can leave the schema dirty.
+3. **Apply migrations.** Run `talos migrate up`. Watch stderr; the command exits non-zero on
+ failure.
+4. **Resolve dirty state if needed.** If migration fails partway through, `migrate up` and
+ `migrate down` will refuse to run with `Error: Database is in dirty state at version N`.
+ Inspect the schema, complete or revert the partial change manually, then run
+ `talos migrate force ` to mark the migration tracker. Never rerun on top of a dirty
+ state.
+5. **Verify with `talos migrate status`.** Confirm the version matches the new binary's expected
+ schema and that `STATUS` reports `OK`, not `DIRTY`.
+6. **Roll the application.** Start replicas of the new binary in a rolling deploy. Old replicas
+ continue serving against the new schema until they are replaced.
+
+## Production safety
+
+- Run `talos migrate up` from a Job, init container, or operator — never from inside the
+ application's startup path. Concurrent migration runners can deadlock or corrupt the migration
+ tracker.
+- Pin the migration image to the same version as the application image. Do not use mutable tags
+ (`latest`, `staging`) for migration jobs.
+- Talos commercial migrations live under `commercial/persistence/migrations/{postgres,mysql,cockroach}/`;
+ the OSS image only ships SQLite migrations and cannot apply them. Use the
+ `oryd/talos-commercial` image for PostgreSQL, MySQL, and CockroachDB.
## DSN examples
@@ -45,7 +72,9 @@ talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
## Kubernetes
-Use an init container or Job:
+Use a Job to apply migrations once, then start the application Deployment. The OSS image
+(`oryd/talos:latest`) only ships SQLite migrations; for PostgreSQL, MySQL, or CockroachDB use
+`oryd/talos-commercial:latest`.
```yaml
apiVersion: batch/v1
@@ -53,11 +82,12 @@ kind: Job
metadata:
name: talos-migrate
spec:
+ backoffLimit: 0 # Do not retry — a failed migration leaves the schema dirty.
template:
spec:
containers:
- name: migrate
- image: oryd/talos:latest
+ image: oryd/talos-commercial:latest # Pin to the same tag as the application image.
command: ["talos", "migrate", "up"]
env:
- name: TALOS_DB_DSN
@@ -65,5 +95,5 @@ spec:
secretKeyRef:
name: talos-secrets
key: dsn
- restartPolicy: OnFailure
+ restartPolicy: Never
```
diff --git a/docs/talos/operate/database/mysql.md b/docs/talos/operate/database/mysql.md
index ff782cfdcc..7a4f0b7ed3 100644
--- a/docs/talos/operate/database/mysql.md
+++ b/docs/talos/operate/database/mysql.md
@@ -32,27 +32,36 @@ export TALOS_DB_DSN="mysql://talos:secret@tcp(db:3306)/talos?tls=true&parseTime=
mysql://user:password@tcp(host:port)/dbname?param=value¶m=value
```
-The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before passing the DSN to the Go MySQL
-driver.
+The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before
+passing the DSN to the Go MySQL driver.
-:::caution Required parameter Always include `parseTime=true` in the DSN. Without it, datetime columns are returned as byte arrays
-instead of `time.Time`, causing runtime errors. :::
+:::caution
+
+Required parameter: always include `parseTime=true` in the DSN. Without it, datetime columns are
+returned as byte arrays instead of `time.Time`, causing runtime errors.
+
+:::
## DSN parameters
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
+database driver.
-| Parameter | Type | Default | Description |
-| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
-| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
-| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
-| `max_conn_lifetime` | duration | `0` (unlimited) | Maximum age of a connection before it is closed and replaced |
-| `max_conn_idle_time` | duration | `0` (unlimited) | Maximum time a connection can sit idle before it is closed |
+| Parameter | Type | Default | Description |
+| -------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
+| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
+| `max_conn_lifetime` | duration | `30m` | Maximum age of a connection before it is closed and replaced |
+| `max_conn_idle_time` | duration | `10m` | Maximum time a connection can sit idle before it is closed |
Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
+Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are
+recycled through load balancers and DNS rotation. Setting either to `0` disables the recycle and
+is **not recommended** outside development.
+
MySQL uses standard `database/sql` pooling only. There is no advanced pool mode.
### MySQL driver parameters
@@ -89,8 +98,8 @@ Pool behavior:
### Pool sizing
-Start with 25 connections per instance. The total pool across all instances should stay below MySQL's `max_connections` (default:
-151).
+Start with 25 connections per instance. The total pool across all instances should stay below
+MySQL's `max_connections` (default: 151).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -98,8 +107,9 @@ Start with 25 connections per instance. The total pool across all instances shou
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use ProxySQL or MySQL Router to multiplex |
-For large deployments, place [ProxySQL](https://proxysql.com/) or [MySQL Router](https://dev.mysql.com/doc/mysql-router/en/)
-between Talos and MySQL for connection multiplexing.
+For large deployments, place [ProxySQL](https://proxysql.com/) or
+[MySQL Router](https://dev.mysql.com/doc/mysql-router/en/) between Talos and MySQL for connection
+multiplexing.
## Database preparation
diff --git a/docs/talos/operate/database/postgresql.md b/docs/talos/operate/database/postgresql.md
index 98f230b91a..26c7837dcb 100644
--- a/docs/talos/operate/database/postgresql.md
+++ b/docs/talos/operate/database/postgresql.md
@@ -7,8 +7,8 @@ sidebar_custom_props:
# PostgreSQL
-PostgreSQL is the recommended production database backend. It provides connection pooling, ACID transactions, and
-high-availability via streaming replication.
+PostgreSQL is the recommended production database backend. It provides connection pooling, ACID
+transactions, and high-availability via streaming replication.
## Supported versions
@@ -39,18 +39,23 @@ Both `postgres://` and `postgresql://` schemes are accepted.
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
+database driver.
-| Parameter | Type | Default | Description |
-| -------------------- | -------- | --------------- | ------------------------------------------------------------ |
-| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
-| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
-| `max_conn_lifetime` | duration | `0` (unlimited) | Maximum age of a connection before it is closed and replaced |
-| `max_conn_idle_time` | duration | `0` (unlimited) | Maximum time a connection can sit idle before it is closed |
-| `pool_mode` | string | `standard` | Pool implementation: `standard` or `advanced` (see below) |
+| Parameter | Type | Default | Description |
+| -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------ |
+| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
+| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
+| `max_conn_lifetime` | duration | `30m` | Maximum age of a connection before it is closed and replaced |
+| `max_conn_idle_time` | duration | `10m` | Maximum time a connection can sit idle before it is closed |
+| `pool_mode` | string | `standard` | Pool implementation: `standard` or `advanced` (see below) |
Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
+Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are
+recycled through load balancers, DNS rotation, and PostgreSQL `tcp_keepalives_*`. Setting either
+to `0` disables the recycle and is **not recommended** outside development.
+
### PostgreSQL driver parameters
These parameters are passed through to the underlying PostgreSQL driver (`pgx`).
@@ -70,7 +75,8 @@ Talos supports two pool modes for PostgreSQL, controlled by the `pool_mode` DSN
### Standard mode (default)
-Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with all tooling.
+Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with
+all tooling.
```yaml
db:
@@ -86,16 +92,29 @@ Pool behavior:
### Advanced mode
-Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is optimized for Kubernetes and cloud
-environments.
+Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is
+optimized for Kubernetes and cloud environments.
```yaml
db:
- dsn: "postgres://talos:secret@db:5432/talos?pool_mode=advanced"
+ dsn: "postgres://talos:secret@db:5432/talos?pool_mode=advanced&pool_max_conns=50&pool_min_conns=2&pool_max_conn_lifetime=30m&pool_max_conn_idle_time=10m"
```
-In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the DSN. The `max_conns`,
-`max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters are not used — pgxpool manages its own pool.
+In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the
+DSN. The `max_conns`, `max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters
+are **ignored** — use the `pool_*` equivalents instead.
+
+| pgxpool parameter | Default | Description |
+| ------------------------- | ---------------------- | ------------------------------------------------------ |
+| `pool_max_conns` | `4 × runtime.NumCPU()` | Maximum size of the pgxpool connection pool |
+| `pool_min_conns` | `0` | Minimum number of connections kept open |
+| `pool_max_conn_lifetime` | `1h` | Maximum age of a connection before it is replaced |
+| `pool_max_conn_idle_time` | `30m` | Maximum idle time before an idle connection is closed |
+| `pool_health_check_period`| `1m` | Interval between background health checks |
+
+Talos exposes the pgxpool through Go's `database/sql` interface. The wrapper's
+`SetMaxIdleConns` is forced to `0` so that `database/sql` never holds connections idle on top of
+pgxpool — the pgxpool layer is the single source of truth for pool sizing in advanced mode.
Use advanced mode when:
@@ -105,8 +124,8 @@ Use advanced mode when:
## Pool sizing
-Start with 25 connections per instance. The total pool across all instances must stay below PostgreSQL's `max_connections`
-(default: 100).
+Start with 25 connections per instance. The total pool across all instances must stay below
+PostgreSQL's `max_connections` (default: 100).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -114,8 +133,9 @@ Start with 25 connections per instance. The total pool across all instances must
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use PgBouncer to multiplex connections |
-For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL. PgBouncer multiplexes many
-application connections over fewer database connections, allowing you to scale beyond PostgreSQL's connection limit.
+For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL.
+PgBouncer multiplexes many application connections over fewer database connections, allowing you to
+scale beyond PostgreSQL's connection limit.
## Migrations
diff --git a/docs/talos/operate/deploy/edge-proxy.md b/docs/talos/operate/deploy/edge-proxy.md
index edb3e58238..856081afe2 100644
--- a/docs/talos/operate/deploy/edge-proxy.md
+++ b/docs/talos/operate/deploy/edge-proxy.md
@@ -7,7 +7,8 @@ sidebar_custom_props:
# Edge proxy
-Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification latency.
+Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification
+latency.
## Pattern
@@ -38,9 +39,9 @@ graph TB
## How it works
-The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos server. It intercepts `POST`
-requests to `/v2/verify/*` endpoints, caches positive (active) verification responses locally, and proxies everything else to
-upstream unchanged.
+The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos
+server. It intercepts `POST` requests to `/v2alpha1/verify/*` endpoints, caches positive (active)
+verification responses locally, and proxies everything else to upstream unchanged.
```mermaid
sequenceDiagram
@@ -48,27 +49,28 @@ sequenceDiagram
participant Proxy as Edge Proxy
participant Talos as Upstream Talos
- App->>Proxy: POST /v2/verify/apiKey
+ App->>Proxy: POST /v2alpha1/verify/apiKey
alt Cache HIT
Proxy-->>App: 200 OK (cached, sub-ms)
else Cache MISS
- Proxy->>Talos: POST /v2/verify/apiKey
+ Proxy->>Talos: POST /v2alpha1/verify/apiKey
Talos-->>Proxy: 200 OK (active=true)
Note over Proxy: Cache response
Proxy-->>App: 200 OK
end
- App->>Proxy: POST /v2/admin/issuedApiKeys
+ App->>Proxy: POST /v2alpha1/admin/issuedApiKeys
Proxy->>Talos: Proxy unchanged
Talos-->>Proxy: 200 OK
Proxy-->>App: 200 OK
```
-Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the proxy transparently.
+Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the
+proxy transparently.
## Sidecar deployment
-Run the proxy as a sidecar container alongside your application. Your application sends verify requests to `localhost` (sub-ms
-cache hits) instead of the central Talos server.
+Run the proxy as a sidecar container alongside your application. Your application sends verify
+requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
```
┌─────────────────────────────────┐
@@ -81,8 +83,9 @@ cache hits) instead of the central Talos server.
└─────────────────────────────────┘
```
-Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy listens on). All other Talos API
-calls (admin, key management) should go directly to the central server.
+Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy
+listens on). All other Talos API calls (admin, key management) should go directly to the central
+server.
## Configuration
@@ -110,15 +113,16 @@ talos-commercial proxy \
### Cache key generation
-Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent collision attacks. The host
-component ensures tenant isolation in multi-tenant deployments: the same credential cached under `tenant-a.example.com` will not
-be served for requests from `tenant-b.example.com`.
+Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent
+collision attacks. The host component ensures tenant isolation in multi-tenant deployments: the same
+credential cached under `tenant-a.example.com` will not be served for requests from
+`tenant-b.example.com`.
### What gets cached
Only responses that meet **all** of the following criteria are cached:
-- The request is a `POST` to `/v2/verify/*`
+- The request is a `POST` to `/v2alpha1/verify/*`
- The upstream returned HTTP `200 OK`
- The response body contains `"is_active": true`
@@ -126,9 +130,10 @@ Inactive credentials, error responses, and non-verify endpoints are never cached
### TTL calculation
-The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the verification response includes an
-`expires_at` timestamp, the proxy ensures the cached entry expires no later than the credential itself. If `expires_at` is absent,
-the configured `--cache-ttl` is used.
+The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the
+verification response includes an `expires_at` timestamp, the proxy ensures the cached entry expires
+no later than the credential itself. If `expires_at` is absent, the configured `--cache-ttl` is
+used.
### Cache headers
@@ -144,13 +149,14 @@ Every response from the proxy includes an `Ory-Talos-Cache` header:
Clients can bypass the cache by including a `Cache-Control` header:
```bash
-curl -X POST http://localhost:8080/v2/verify/apiKey \
+curl -X POST http://localhost:8080/v2alpha1/verify/apiKey \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{"credential": "phx_..."}'
```
-Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for caching.
+Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for
+caching.
## Health checks
@@ -186,7 +192,10 @@ services:
ports:
- "8080:8080"
environment:
- - DATABASE_URL=postgres://talos:secret@db:5432/talos?sslmode=disable
+ - TALOS_DB_DSN=postgres://talos:secret@db:5432/talos?sslmode=disable
+ - TALOS_CREDENTIALS_ISSUER=https://api.example.com
+ - TALOS_SECRETS_DEFAULT_CURRENT=use-a-random-64-char-pagination-token-secret-generated-at-deploy
+ - TALOS_SECRETS_HMAC_CURRENT=use-a-random-64-char-hmac-secret-for-api-key-checksum-validation
proxy:
image: oryd/talos-commercial:latest
@@ -262,8 +271,10 @@ spec:
## Eventual consistency
-Revocation takes effect in the database immediately but cached verification results persist until the cache TTL expires. To force
-an immediate re-check against upstream, send `Cache-Control: no-cache` on the verification request.
+Revocation takes effect in the database immediately but cached verification results persist until
+the cache TTL expires. To force an immediate re-check against upstream, send
+`Cache-Control: no-cache` on the verification request.
-Choose a `--cache-ttl` that balances latency savings against your revocation propagation requirements. Shorter TTLs provide faster
-revocation propagation at the cost of more upstream requests.
+Choose a `--cache-ttl` that balances latency savings against your revocation propagation
+requirements. Shorter TTLs provide faster revocation propagation at the cost of more upstream
+requests.
diff --git a/docs/talos/operate/deploy/kubernetes.md b/docs/talos/operate/deploy/kubernetes.md
index f0598a974d..77ff3948b3 100644
--- a/docs/talos/operate/deploy/kubernetes.md
+++ b/docs/talos/operate/deploy/kubernetes.md
@@ -4,7 +4,20 @@ title: Kubernetes
# Kubernetes
-## Deployment
+The OSS edition uses an embedded SQLite database, so it cannot scale horizontally — a multi-replica
+Deployment backed by a shared volume will corrupt under concurrent writes. Run the OSS image as a
+single replica or move to the [Commercial edition](../../index.md#editions) for Postgres, MySQL, or
+CockroachDB.
+
+| Edition | Image | Backends | Replicas |
+| ---------- | ------------------------------ | ------------------------------------------- | ----------------------- |
+| OSS | `oryd/talos:latest` | SQLite (embedded) | 1 (single-node only) |
+| Commercial | `oryd/talos-commercial:latest` | PostgreSQL, MySQL, CockroachDB | Horizontally scalable |
+
+## Deployment (Commercial, scalable)
+
+The manifest below uses the commercial image and a SQL backend stored as `dsn` in a Kubernetes
+`Secret`. Adjust `replicas` to your traffic profile.
```yaml
apiVersion: apps/v1
@@ -23,7 +36,7 @@ spec:
spec:
initContainers:
- name: migrate
- image: oryd/talos:latest
+ image: oryd/talos-commercial:latest
command: ["talos", "migrate", "up"]
env:
- name: TALOS_DB_DSN
@@ -33,7 +46,7 @@ spec:
key: dsn
containers:
- name: talos
- image: oryd/talos:latest
+ image: oryd/talos-commercial:latest
args: ["serve", "--config", "/etc/talos/config.yaml"]
ports:
- containerPort: 4420
diff --git a/docs/talos/operate/deploy/separate-planes.md b/docs/talos/operate/deploy/separate-planes.md
index 71f1b759ca..73ccdbef68 100644
--- a/docs/talos/operate/deploy/separate-planes.md
+++ b/docs/talos/operate/deploy/separate-planes.md
@@ -4,18 +4,22 @@ title: Separate admin and data planes
# Separate admin and data planes
-In production, you can deploy the admin plane and data plane as separate processes for independent scaling and security isolation.
+In production, you can deploy the admin plane and data plane as separate processes for independent
+scaling and security isolation.
-## Why separate
+## Why run them separately
-- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be exposed at the edge
-- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane handles lower-volume
- management
-- **Network isolation**: Admin plane behind internal firewall; data plane behind public load balancer
+- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be
+ exposed at the edge
+- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane
+ handles lower-volume management
+- **Network isolation**: Admin plane behind internal firewall; data plane behind public load
+ balancer
## Architecture
-Both planes share the same database. The admin plane writes keys; the data plane reads and verifies them.
+Both planes share the same database. The admin plane writes keys; the data plane reads and verifies
+them.
```mermaid
graph TB
@@ -49,24 +53,46 @@ talos serve check --config config.yaml
## Configuration
-Both deployments use the same config file or environment variables. The key difference is network exposure:
+Both deployments use the same config file or environment variables. The key difference is network
+exposure:
-**Admin plane** — bind to internal network only:
+Both processes need the full configuration block (`secrets`, `credentials`,
+`db`). The split is driven by the `serve` subcommand and the bind address, not
+by stripping config keys.
+
+**Admin plane** — bind to an internal address:
```yaml
serve:
http:
host: "10.0.0.1"
port: 4420
+credentials:
+ issuer: "https://api.example.com"
+secrets:
+ default:
+ current: "use-the-same-pagination-secret-on-both-planes--64chars"
+ hmac:
+ current: "use-the-same-hmac-secret-on-both-planes-or-verify-fails-64chars"
```
-**Data plane** — bind to all interfaces with caching:
+**Data plane** — bind to all interfaces with caching. Use the same secrets and
+issuer as the admin plane so the two processes derive identical key checksums.
+If you co-locate both planes on the same host, change one port (for example, the
+admin plane on `4421`):
```yaml
serve:
http:
host: "0.0.0.0"
port: 4420
+credentials:
+ issuer: "https://api.example.com"
+secrets:
+ default:
+ current: "use-the-same-pagination-secret-on-both-planes--64chars"
+ hmac:
+ current: "use-the-same-hmac-secret-on-both-planes-or-verify-fails-64chars"
cache:
type: "memory"
ttl: "5m"
@@ -74,4 +100,5 @@ cache:
## Network policies
-Restrict admin plane access to internal services only. Data plane can accept traffic from any source.
+Restrict admin plane access to internal services only. Data plane can accept traffic from any
+source.
diff --git a/docs/talos/operate/index.md b/docs/talos/operate/index.md
index 199e241dce..f4a61e2667 100644
--- a/docs/talos/operate/index.md
+++ b/docs/talos/operate/index.md
@@ -5,7 +5,9 @@ description: Install, configure, and deploy Ory Talos
# Operate Ory Talos
-This section covers everything platform engineers need to run Talos in production.
+How to install, configure, deploy, and operate Talos. Pages tagged `[commercial]` apply to the
+Commercial edition only — the OSS edition runs as a single-node binary with embedded SQLite and
+covers the install, configure, secrets, TLS, monitoring, and security-hardening guides below.
## Getting started
@@ -16,20 +18,23 @@ This section covers everything platform engineers need to run Talos in productio
## Production checklist
-Before going to production, review these guides:
+Before going to production, review these guides (apply to OSS and Commercial):
- **[Secrets management](secrets.md)** — configure HMAC secrets and JWKS signing keys
- **[TLS](tls.md)** — enable TLS termination or configure a reverse proxy
-- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and health checks
-- **[Security hardening](security-hardening.md)** — production security checklist
+- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and
+ health checks
+- **[Security hardening](security-hardening.md)** — production security checklist, including admin
+ plane authentication
- **[Benchmarks](benchmarks.md)** — performance baselines and load testing
-## Commercial features
+## Commercial-only features
-These features require the Commercial edition:
+The OSS edition is single-node SQLite. Horizontal scale, SQL backends, distributed caching, edge
+deployment, and multi-tenancy require the [Commercial edition](../index.md#editions):
-- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**, **[CockroachDB](database/cockroachdb.md)** —
- production-grade SQL backends
+- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**,
+ **[CockroachDB](database/cockroachdb.md)** — production-grade SQL backends
- **[Caching](cache/index.md)** — in-memory and Redis caching for sub-millisecond verification
- **[Edge proxy](deploy/edge-proxy.md)** — deploy data plane at the edge
- **[Multi-tenancy](multi-tenancy.md)** — serve multiple tenants from a single cluster
@@ -41,5 +46,6 @@ Talos separates administrative operations (issuing, revoking) from verification:
- **Admin plane** — manages key lifecycle. Runs behind your internal network.
- **Data plane** — verifies credentials at the edge. Horizontally scalable with caching.
-You can run both planes in a single process (`talos serve`) or split them for production (`talos serve admin`,
-`talos serve check`). See [Separate planes](deploy/separate-planes.md) for details.
+You can run both planes in a single process (`talos serve`) or split them for production
+(`talos serve admin`, `talos serve check`). See [Separate planes](deploy/separate-planes.md) for
+details.
diff --git a/docs/talos/operate/install.md b/docs/talos/operate/install.md
index 5a6c271fed..36283132ad 100644
--- a/docs/talos/operate/install.md
+++ b/docs/talos/operate/install.md
@@ -23,7 +23,8 @@ The binary is at `.bin/talos`. SQLite is the only supported database backend in
### Commercial edition
-The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin UI:
+The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin
+UI:
```bash
go build -tags commercial -o .bin/talos-commercial .
@@ -34,7 +35,7 @@ go build -tags commercial -o .bin/talos-commercial .
```bash
-./.bin/talos version
+./.bin/talos --version
./.bin/talos help
```
diff --git a/docs/talos/operate/monitoring/health-checks.md b/docs/talos/operate/monitoring/health-checks.md
index b3fce3f677..eec21edfee 100644
--- a/docs/talos/operate/monitoring/health-checks.md
+++ b/docs/talos/operate/monitoring/health-checks.md
@@ -34,8 +34,8 @@ readinessProbe:
## Load balancer
-Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server is ready to accept traffic and
-503 when it is not (e.g., during startup or shutdown).
+Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server
+is ready to accept traffic and 503 when it is not (e.g., during startup or shutdown).
## Suppressing health logs
diff --git a/docs/talos/operate/monitoring/index.md b/docs/talos/operate/monitoring/index.md
index f0a92dbdad..003e735225 100644
--- a/docs/talos/operate/monitoring/index.md
+++ b/docs/talos/operate/monitoring/index.md
@@ -4,7 +4,8 @@ title: Monitoring
# Monitoring
-Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health endpoints.
+Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health
+endpoints.
- [Prometheus metrics](metrics.md) — request counts, latencies, and pool sizes
- [OpenTelemetry tracing](tracing.md) — distributed request traces
diff --git a/docs/talos/operate/monitoring/metrics.md b/docs/talos/operate/monitoring/metrics.md
index 6f626d23ff..88371cd9a1 100644
--- a/docs/talos/operate/monitoring/metrics.md
+++ b/docs/talos/operate/monitoring/metrics.md
@@ -28,7 +28,7 @@ GET http://localhost:4422/metrics
| ---------- | --------------------------------------------------------- | ------------------------------------------------------ |
| `method` | HTTP method (lowercase) | All except `http_requests_in_flight` |
| `code` | HTTP status code | All except `http_requests_in_flight` |
-| `endpoint` | Route template (e.g., `/v2/admin/issuedApiKeys/{key_id}`) | `http_requests_total`, `http_request_duration_seconds` |
+| `endpoint` | Route template (e.g., `/v2alpha1/admin/issuedApiKeys/{key_id}`) | `http_requests_total`, `http_request_duration_seconds` |
## Configuration
diff --git a/docs/talos/operate/monitoring/tracing.md b/docs/talos/operate/monitoring/tracing.md
index 43baf48812..9bb00521b5 100644
--- a/docs/talos/operate/monitoring/tracing.md
+++ b/docs/talos/operate/monitoring/tracing.md
@@ -36,5 +36,6 @@ export TALOS_TRACING_SAMPLE_RATE=0.01
## Traced operations
-Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP request handling. Each trace
-includes the Network ID (for multi-tenant deployments) and relevant key identifiers.
+Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP
+request handling. Each trace includes the Network ID (for multi-tenant deployments) and relevant key
+identifiers.
diff --git a/docs/talos/operate/multi-tenancy.md b/docs/talos/operate/multi-tenancy.md
index fdb9cf9704..3140c7ea1e 100644
--- a/docs/talos/operate/multi-tenancy.md
+++ b/docs/talos/operate/multi-tenancy.md
@@ -7,14 +7,18 @@ sidebar_custom_props:
# Multi-tenancy
-Talos supports multi-tenancy through Network IDs (NID) derived from the request hostname.
+Talos supports multi-tenancy through Network IDs (NID) derived from the request hostname. Each
+tenant runs on its own hostname and has its own NID, configuration overlay, and isolated data.
## How it works
-1. Each tenant is assigned a unique Network ID
-2. The hostname middleware extracts the NID from the incoming request's hostname
-3. All database operations are scoped to the NID via composite primary keys `(nid, key_id)`
-4. Keys created in one tenant cannot be accessed or verified in another
+1. Each tenant is assigned a unique Network ID (UUID).
+2. The hostname middleware extracts the hostname from the incoming request, normalizes it, and
+ resolves it to a configured tenant.
+3. The contextualizer attaches the NID and any per-tenant configuration overlay to the request
+ context.
+4. All database operations are scoped to the NID via composite primary keys `(nid, key_id)`. Keys
+ created in one tenant cannot be accessed or verified in another.
## Configuration
@@ -30,16 +34,112 @@ multitenancy:
config_path: "/etc/talos/tenant2.yaml"
```
-Each entry maps a hostname to a network. The `hostname` is matched against the incoming request's `Host` / `X-Forwarded-Host`
-header (port is stripped before comparison). The `id` is the tenant's UUID. The `config_path` points to a network-specific
-configuration file (absolute or relative to the working directory).
+| Field | Required | Description |
+| ------------- | -------- | ------------------------------------------------------------------------------------ |
+| `hostname` | Yes | Tenant hostname matched against the normalized request hostname (see below) |
+| `id` | Yes | Tenant UUID written to the `nid` column of every row created on this tenant |
+| `config_path` | No | Path to a YAML file containing per-tenant business-logic overrides (see below) |
+
+Hostnames must be unique after normalization. Talos refuses to start if two entries normalize to
+the same value.
+
+## Hostname source and normalization
+
+By default Talos uses `r.Host` (the HTTP `Host` header) for tenant routing. To prefer
+`X-Forwarded-Host`, set:
+
+```yaml
+serve:
+ http:
+ trust_forwarded_host: true
+```
+
+Set this **only** when Talos runs behind a reverse proxy that strips the client-supplied
+`X-Forwarded-Host` and rewrites it to the canonical edge hostname. Trusting the header in front of
+an unfiltered ingress lets external callers spoof tenant identity by sending a forged
+`X-Forwarded-Host`.
+
+Hostnames are normalized before lookup:
+
+- Lowercased (`Tenant1.Example.com` → `tenant1.example.com`)
+- Port stripped (`tenant1.example.com:8443` → `tenant1.example.com`)
+- IPv6 brackets stripped (`[2001:db8::1]:443` → `2001:db8::1`)
+- Rejected if the bare hostname exceeds 253 characters (DNS maximum), contains null bytes, or
+ contains non-printable runes — these requests are treated as if the hostname is unknown.
+
+## Unknown hostname behavior
+
+Requests whose normalized hostname does not match any configured network return HTTP `404` with
+`code: NOT_FOUND` and reason `network not found`. The middleware does not fall back to a default
+tenant. Configure a wildcard or catch-all hostname explicitly if you need one.
+
+## Per-tenant configuration overlays
+
+`config_path` points to a YAML file merged on top of the base server configuration at request
+time. Per-tenant overlays are **business-logic only**:
+
+| Allowed override prefixes | Purpose |
+| --------------------------------------- | ------------------------------------------------ |
+| `talos.*` | Tenant-specific business logic |
+| `secrets.*` | Per-tenant HMAC and pagination secrets |
+| `credentials.*` | Per-tenant key prefixes, issuer, JWKS URLs |
+| `cache.*` | Per-tenant cache backend selection |
+
+Server-wide settings — `db.*`, `serve.*` (`http`, `grpc`, `tls`), `multitenancy.*`,
+`tracing.*` — are **always global** and cannot be overridden per tenant. Setting them in a tenant
+overlay has no effect.
## Database isolation
-Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every query includes the NID, ensuring
-complete data isolation at the SQL level.
+Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every
+query includes the NID, ensuring complete data isolation at the SQL level. Cross-tenant queries
+are impossible from application code because the NID is read from the request context, never from
+request parameters or response bodies.
## Defense-in-depth
-Token claims embed the NID at derivation time. During verification, the claim NID is validated against the context NID (from
-hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`, preventing cross-tenant token replay.
+Token claims embed the NID at derivation time. During verification, the claim NID is validated
+against the context NID (from hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`,
+preventing cross-tenant token replay.
+
+## Provisioning a new tenant
+
+1. **Generate a tenant UUID:** `uuidgen` (or `python -c 'import uuid; print(uuid.uuid4())'`).
+2. **Pick a hostname** that resolves to your Talos data plane (e.g., `tenant3.talos.example.com`)
+ and add a DNS record or load-balancer rule for it.
+3. **Create the tenant overlay** at `/etc/talos/tenant3.yaml` with any per-tenant business
+ settings:
+
+ ```yaml
+ credentials:
+ issuer: "https://api.tenant3.example.com"
+ api_keys:
+ prefix:
+ current: "t3"
+ ```
+
+4. **Add the network entry** to the base config:
+
+ ```yaml
+ multitenancy:
+ networks:
+ - hostname: "tenant3.talos.example.com"
+ id: "550e8400-e29b-41d4-a716-446655440003"
+ config_path: "/etc/talos/tenant3.yaml"
+ ```
+
+5. **Reload or restart Talos.** The contextualizer picks up the new entry on the next request.
+6. **Verify the route** with a curl against the admin plane:
+
+ ```bash
+ curl -sf -X POST "https://tenant3.talos.example.com/v2alpha1/admin/issuedApiKeys" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"smoketest","actor_id":"system"}' | jq
+ ```
+
+ The response should include the new tenant's prefix (`t3_v1_…`).
+
+To deprovision a tenant, remove the entry from `multitenancy.networks` and reload. Existing keys
+remain in the database under that NID; delete them with a tenant-scoped admin call before
+removing the entry, or run a SQL `DELETE FROM api_keys WHERE nid = ''` after the entry is
+gone.
diff --git a/docs/talos/operate/secrets.md b/docs/talos/operate/secrets.md
index 882588739a..57d70f7552 100644
--- a/docs/talos/operate/secrets.md
+++ b/docs/talos/operate/secrets.md
@@ -4,51 +4,115 @@ title: Secret management
# Secret management
-Talos uses HMAC secrets for API key checksum generation and verification.
+Talos uses two independent secret families:
+
+- `secrets.hmac.*` — keys API key checksums and derives the macaroon root key. **Required at
+ startup**; Talos exits with `project has no HMAC key configured` if `secrets.hmac.current` is
+ unset.
+- `secrets.pagination.*` (preferred) or `secrets.default.*` (fallback) — encrypts opaque
+ pagination tokens. Required to use list endpoints.
+
+Each secret must be at least 32 characters. Use 64 random characters for new deployments.
## Configuration
```yaml
secrets:
- default:
- current: "a-32-byte-or-longer-secret-here!"
- retired:
- - "previous-secret-that-was-rotated"
hmac:
- current: "optional-separate-hmac-secret-32chars"
- retired: []
+ current: "use-a-random-64-char-hmac-secret-for-api-key-checksum-validation"
+ retired:
+ - "previous-hmac-secret-rotated-out-on-2026-03-01-padded-to-64chars-"
+ pagination:
+ current: "use-a-random-64-char-pagination-token-secret-generated-at-deploy"
+ retired:
+ - "previous-pagination-token-secret-rotated-out-on-2026-03-01--64chars"
```
+If `secrets.pagination.current` is empty, Talos falls back to `secrets.default.current`. Use
+`secrets.pagination.*` for new deployments; `secrets.default.*` is retained for backwards
+compatibility with earlier configurations.
+
## Secret types
-| Secret | Purpose | Required |
-| ------------------------- | ----------------------------------------- | ------------------ |
-| `secrets.default.current` | Default secret for HMAC and pagination | Yes (min 32 chars) |
-| `secrets.hmac.current` | Dedicated HMAC secret (overrides default) | No |
+| Secret | Purpose | Required |
+| ---------------------------- | ---------------------------------------------------------------- | ----------------------- |
+| `secrets.hmac.current` | API key checksum HMAC and macaroon root-key derivation | Yes (min 32 chars) |
+| `secrets.hmac.retired` | Older HMAC secrets accepted during verification only | No |
+| `secrets.pagination.current` | Pagination-token encryption (preferred over `secrets.default`) | One of pagination/default required for list endpoints |
+| `secrets.pagination.retired` | Older pagination secrets accepted during decryption only | No |
+| `secrets.default.current` | Pagination-token fallback when `secrets.pagination.current` unset | No (use `pagination.*`) |
+| `secrets.default.retired` | Older fallback secrets accepted during decryption only | No |
+
+The HMAC and pagination secret families are independent. Rotate them on independent schedules and
+never reuse the same value across families.
+
+## Macaroon root-key derivation
+
+Talos does not store a separate macaroon signing secret. The macaroon root key is derived
+deterministically from `secrets.hmac.current` using a domain-separated HMAC-SHA256:
+
+```
+macaroon_root_key = HMAC-SHA256(secrets.hmac.current, "talos/macaroon/v1/root-key")
+```
+
+The fixed domain string `talos/macaroon/v1/root-key` prevents the derived key from colliding with
+other uses of the HMAC secret (such as API key checksums). All admin and data plane processes
+configured with the same `secrets.hmac.current` derive the same macaroon root key, so any node can
+verify macaroons issued by any other node without out-of-band key distribution.
+
+Rotating `secrets.hmac.current` rotates both the API key checksum key and the macaroon root key
+at once. Verification falls back through `secrets.hmac.retired` for both purposes.
+
+## Pagination-token secret
-If `secrets.hmac.current` is not set, Talos falls back to `secrets.default.current`.
+List endpoints (`ListIssuedAPIKeys`, `ListImportedAPIKeys`, `ListBatchVerifications`, …) return an
+opaque `next_page_token` that encrypts the cursor (key ID and tenant ID) with NaCl secretbox. The
+encryption key is derived from `secrets.pagination.current` (or `secrets.default.current` as a
+fallback).
+
+Page tokens are tenant-scoped: a token issued under tenant A returns
+`page token network mismatch` if replayed against tenant B.
+
+Rotating the pagination secret invalidates outstanding tokens unless the previous secret remains
+in the `retired` list. Keep the previous secret in `retired` for at least the longest paging
+session you expect (typically a few minutes).
## Secret rotation
-1. Add the current secret to the `retired` array
-2. Set a new `current` secret
-3. Restart Talos (or wait for config hot-reload)
+1. Move the existing `current` value into the `retired` list.
+2. Set a new `current` value generated with a cryptographically secure RNG.
+3. Either restart Talos or wait for config hot-reload to pick up the change.
```yaml
secrets:
- default:
- current: "new-secret-32-chars-minimum-here!"
+ hmac:
+ current: "newly-rotated-hmac-secret-padded-to-64-random-chars--------"
retired:
- - "old-secret-that-was-previously-current"
+ - "previous-hmac-secret-still-trusted-during-verification-padded--"
```
-During verification, Talos tries the current secret first, then each retired secret in order. This ensures existing API keys
-remain valid after rotation.
+During verification, Talos tries `current` first, then each entry in `retired` in order. New keys
+are always issued with `current`. Remove a value from `retired` only after every key issued with it
+has expired or been rotated.
+
+## Generating secrets
+
+```bash
+openssl rand -base64 48 | tr -d '\n+/=' | cut -c1-64
+```
+
+This emits a 64-character URL-safe value suitable for either secret family.
## Environment variables
```bash
-export TALOS_SECRETS_DEFAULT_CURRENT="my-secret-32-chars-minimum"
-export TALOS_SECRETS_DEFAULT_RETIRED="old-secret-1,old-secret-2"
-export TALOS_SECRETS_HMAC_CURRENT="optional-hmac-secret"
+export TALOS_SECRETS_HMAC_CURRENT="64-char-hmac-secret-required-for-startup"
+export TALOS_SECRETS_HMAC_RETIRED="previous-hmac-secret-1,previous-hmac-secret-2"
+export TALOS_SECRETS_PAGINATION_CURRENT="64-char-pagination-token-secret"
+export TALOS_SECRETS_PAGINATION_RETIRED="previous-pagination-secret-1"
+# Legacy fallback; prefer TALOS_SECRETS_PAGINATION_CURRENT
+export TALOS_SECRETS_DEFAULT_CURRENT="64-char-fallback-pagination-secret"
```
+
+Inject these from a secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, or
+Kubernetes `Secret`); never check secrets into version control.
diff --git a/docs/talos/operate/security-hardening.md b/docs/talos/operate/security-hardening.md
index 930e6c9fef..8b0865cec3 100644
--- a/docs/talos/operate/security-hardening.md
+++ b/docs/talos/operate/security-hardening.md
@@ -6,24 +6,35 @@ title: Security hardening
## Network
-- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance and revocation and should never
- be exposed to the public internet.
-- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or terminate TLS at the load
- balancer).
+- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance
+ and revocation and should never be exposed to the public internet.
+- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or
+ terminate TLS at the load balancer).
- **Separate admin and data planes** in production for independent security boundaries.
## Secrets
-- **Use strong HMAC secrets** of at least 32 characters, generated with a cryptographically secure random generator.
-- **Use separate HMAC secrets** (`secrets.hmac.current`) rather than relying on the default secret.
-- **Rotate secrets regularly** using the retired array. Verification tries current + retired secrets automatically.
-- **Never commit secrets** to version control. Use environment variables or a secrets manager.
+- **Configure both required secrets** before starting Talos: `secrets.default.current` (pagination
+ tokens) and `secrets.hmac.current` (API key checksums and macaroon root keys). Both must be at
+ least 32 characters; aim for 64 random characters.
+- **Generate secrets cryptographically**: `openssl rand -base64 48 | tr -d '\n+/=' | cut -c1-64`.
+- **Rotate secrets regularly** by promoting `current` to `retired` and setting a new `current`.
+ Verification tries `current` first, then every value in `retired`, so existing keys keep
+ working through the rotation window.
+- **Never commit secrets** to version control. Inject them via environment variables
+ (`TALOS_SECRETS_DEFAULT_CURRENT`, `TALOS_SECRETS_HMAC_CURRENT`) or a secrets manager.
## API keys
- **Set TTL on all keys** to limit exposure from leaked credentials.
-- **Revoke compromised keys immediately** using `POST /v2/admin/apiKeys/{id}:revoke`.
-- **Use scopes** to limit key permissions to the minimum required.
+- **Revoke compromised keys immediately** using
+ `POST /v2alpha1/admin/issuedApiKeys/{key_id}:revoke` or
+ `POST /v2alpha1/admin/importedApiKeys/{key_id}:revoke`.
+- **Limit scopes** on issued and imported keys to the minimum required. Talos stores scopes as
+ metadata on the key and returns them on verification; your application is responsible for
+ enforcing them during request handling.
+- **Bind keys to caller IPs** with `ip_restriction.allowed_cidrs` to reduce blast radius if a key
+ leaks. See [IP restrictions](../integrate/ip-restrictions.md).
## Caching
@@ -35,3 +46,28 @@ title: Security hardening
- **Monitor verification error rates** for anomalous patterns (credential stuffing, brute force).
- **Enable tracing** to audit key usage and identify suspicious activity.
- **Set up alerts** on `http_requests_total{code=~"4.."}` and `http_requests_total{code=~"5.."}`.
+
+## Admin plane authentication
+
+**Talos ships no built-in authentication for the admin plane.** Any caller that can reach the admin
+HTTP listener can issue, update, and revoke keys for any tenant. Treat the admin plane as a trusted
+internal service and put authentication in front of it.
+
+Recommended patterns:
+
+- **Identity-aware proxy (IAP)**: terminate authentication at a gateway (Google Cloud IAP, AWS ALB
+ with Cognito, Cloudflare Access, oauth2-proxy) and forward only authenticated requests to the
+ admin plane. Pin the admin listener to a private network so requests cannot bypass the gateway.
+- **mTLS at the load balancer**: require client certificates issued by an internal CA. Reject
+ unauthenticated TLS handshakes at the LB, then forward plain HTTP to the admin plane on a
+ private network.
+- **Service mesh policy**: in Kubernetes, use Istio `AuthorizationPolicy` or Linkerd authorization
+ policies to allow only specific service accounts to call the admin plane.
+
+Whichever pattern you choose:
+
+- Bind the admin listener to a non-routable address (`127.0.0.1`, `10.x`, or a Kubernetes
+ `ClusterIP`); never expose it to the public internet.
+- Run the data plane on a separate listener so verification traffic does not need to traverse the
+ admin auth path. See [Separate admin and data planes](deploy/separate-planes.md).
+- Audit-log every admin call at the gateway. Talos itself does not record caller identity.
diff --git a/docs/talos/operate/tls.md b/docs/talos/operate/tls.md
index 5e108ed273..6e630b71ba 100644
--- a/docs/talos/operate/tls.md
+++ b/docs/talos/operate/tls.md
@@ -4,7 +4,8 @@ title: TLS configuration
# TLS configuration
-Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy, Caddy) for TLS termination:
+Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy,
+Caddy) for TLS termination:
```
Client --[HTTPS]--> Load Balancer --[HTTP]--> Talos
diff --git a/docs/talos/operate/troubleshooting.md b/docs/talos/operate/troubleshooting.md
index 57082b79ca..0e4cca1bed 100644
--- a/docs/talos/operate/troubleshooting.md
+++ b/docs/talos/operate/troubleshooting.md
@@ -29,7 +29,8 @@ Verify `serve.http.host` and `serve.http.port` in your config.
talos migrate status --database "sqlite:///path/to/db"
```
-If a migration failed partway through, inspect the database schema and retry with `talos migrate up`.
+If a migration failed partway through, inspect the database schema and retry with
+`talos migrate up`.
### Secret too short
@@ -42,14 +43,15 @@ Set `secrets.default.current` to a string of at least 32 characters.
### Key verification returns not found
1. Verify the key was issued on the same Talos instance (or shared database)
-2. Check if the key has been revoked: `GET /v2/admin/issuedApiKeys/{key_id}`
+2. Check if the key has been revoked: `GET /v2alpha1/admin/issuedApiKeys/{key_id}`
3. If using caching, try with `Cache-Control: no-cache` header
-4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was issued
+4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was
+ issued
### Invalid API key format
-The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret (not the key_id) is being
-sent.
+The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret
+(not the key_id) is being sent.
## Debug logging
diff --git a/docs/talos/quickstart/docker-commercial.md b/docs/talos/quickstart/docker-commercial.md
index 193d9345e0..561c3d6a25 100644
--- a/docs/talos/quickstart/docker-commercial.md
+++ b/docs/talos/quickstart/docker-commercial.md
@@ -48,7 +48,7 @@ echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "commercial-test",
@@ -87,7 +87,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}" | jq .
```
@@ -109,7 +109,8 @@ docker compose -f docker-compose.commercial.yaml down -v
## Prerequisites
-You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free edition first.
+You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free
+edition first.
## Next steps
diff --git a/docs/talos/quickstart/index.md b/docs/talos/quickstart/index.md
index 651c176a7c..db504c9abf 100644
--- a/docs/talos/quickstart/index.md
+++ b/docs/talos/quickstart/index.md
@@ -7,8 +7,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
# Quickstart
-This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker Compose. You need Docker.
-Examples use the Talos CLI (with curl as an alternative).
+This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker
+Compose. You need Docker. Examples use the Talos CLI (with curl as an alternative).
@@ -19,8 +19,8 @@ Examples use the Talos CLI (with curl as an alternative).
docker compose -f docker-compose.oss.yaml up --build -d
```
-This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at http://localhost:3001). Migrations run
-automatically.
+This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at
+http://localhost:3001). Migrations run automatically.
Wait for the server to become healthy:
@@ -74,7 +74,7 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```bash
# Issue a key and capture the response
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "My first key",
@@ -87,7 +87,7 @@ echo "$RESPONSE" | jq .
# Save the secret and key ID for later steps
API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
@@ -118,7 +118,7 @@ talos keys verify "$API_SECRET" -e "$TALOS_URL"
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}")
@@ -128,7 +128,8 @@ echo "$VERIFY_RESPONSE" | jq .
-The response confirms the key is active and returns the associated metadata (actor, scopes, expiration).
+The response confirms the key is active and returns the associated metadata (actor, scopes,
+expiration).
## Revoke the key
@@ -147,9 +148,9 @@ talos keys revoke "$KEY_ID" --reason superseded -e "$TALOS_URL"
```bash
-curl -s -X POST "$TALOS_URL/v2/admin/apiKeys/${KEY_ID}:revoke" \
+curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys/${KEY_ID}:revoke" \
-H "Content-Type: application/json" \
- -d '{"reason": "Quickstart cleanup"}'
+ -d '{"reason":"REVOCATION_REASON_SUPERSEDED"}'
echo ""
echo "Key revoked"
```
@@ -173,7 +174,7 @@ echo "Revocation confirmed"
```bash
-REVOKE_CHECK=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+REVOKE_CHECK=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d "{\"credential\":\"$API_SECRET\"}")
@@ -192,8 +193,8 @@ fi
-Revocation is immediate. Even though the key is cryptographically valid, the server checks the revocation list on every
-verification request.
+Revocation is immediate. Even though the key is cryptographically valid, the server checks the
+revocation list on every verification request.
## Stop the server
@@ -209,6 +210,7 @@ docker compose -f docker-compose.oss.yaml down -v
## Next steps
-- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential operations
+- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential
+ operations
- **[Operations guide](../operate/index.md)** — install, configure, and deploy Talos in production
- **[Architecture](../concepts/architecture.md)** — how the admin and data planes work
diff --git a/docs/talos/quickstart/preview.mdx b/docs/talos/quickstart/preview.mdx
index a74039994c..8e9a0a052c 100644
--- a/docs/talos/quickstart/preview.mdx
+++ b/docs/talos/quickstart/preview.mdx
@@ -24,7 +24,7 @@ steps below; the `curl` examples are the preview baseline, and the Talos CLI is
## Pull the image
```bash
-docker pull europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6
+docker pull europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8
```
## Start Postgres
@@ -53,7 +53,6 @@ credentials:
derived_tokens:
default_ttl: "1h"
jwt:
- algorithm: "EdDSA"
signing_keys:
urls:
- "base64://eyAgImtleXMiOiBbICAgIHsgICAgICAiYWxnIjogIkVkRFNBIiwgICAgICAiY3J2IjogIkVkMjU1MTkiLCAgICAgICJkIjogIjl3VTNfV3p0dmx3TXg0SGlfN2dsSVduY09XNlVIR2I5amxDdDZEZkVGa2MiLCAgICAgICJraWQiOiAiZG9ja2VyLWRldi0wMDEiLCAgICAgICJrdHkiOiAiT0tQIiwgICAgICAidXNlIjogInNpZyIsICAgICAgIngiOiAiNGtTQTdtNU5jYnFDUC1mZk9fNGhQM2tsNHB0NGctLTNRQ21zQmwzb05lVSIgICAgfSAgXX0="
@@ -86,7 +85,7 @@ Initialize the Postgres schema before the first server start:
```bash
docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
migrate up --database "postgres://talos:talos@talos-postgres:5432/talos?sslmode=disable"
```
@@ -96,7 +95,7 @@ docker run --rm --network talos-preview \
docker run -d --name talos --network talos-preview \
-p 8080:8080 -p 4422:4422 \
-v "$PWD/config.yaml:/etc/talos/config.yaml:ro" \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
serve --config /etc/talos/config.yaml
```
@@ -139,7 +138,7 @@ Create an issued key on the admin plane and save its secret for later steps. For
```bash
RESPONSE=$(docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
keys issue "preview-issued-key" \
--actor preview-user \
--scopes "read:profile,write:profile" \
@@ -152,15 +151,15 @@ echo "$RESPONSE" | jq .
API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-export API_SECRET=$API_SECRET
-export KEY_ID=$KEY_ID
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/issuedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{
"name": "preview-issued-key",
@@ -174,8 +173,8 @@ echo "$RESPONSE" | jq .
API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-export API_SECRET=$API_SECRET
-export KEY_ID=$KEY_ID
+echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```
@@ -195,7 +194,7 @@ Send the issued key secret to the unified verify endpoint. For the full response
```bash
docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
keys verify "$API_SECRET" -e "http://talos:8080"
```
@@ -203,7 +202,7 @@ docker run --rm --network talos-preview \
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$API_SECRET\"}")
@@ -227,7 +226,7 @@ Mint a short-lived JWT from the issued key with a custom claim. For the full req
```bash
RESPONSE=$(docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
keys derive-token "$API_SECRET" \
--algorithm jwt \
--ttl 1h \
@@ -238,14 +237,14 @@ RESPONSE=$(docker run --rm --network talos-preview \
echo "$RESPONSE" | jq .
JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-export JWT_TOKEN=$JWT_TOKEN
+echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
```
```bash
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
-H "Content-Type: application/json" \
-d "{
\"credential\": \"$API_SECRET\",
@@ -257,7 +256,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:derive" \
echo "$RESPONSE" | jq .
JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-export JWT_TOKEN=$JWT_TOKEN
+echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
```
@@ -279,7 +278,7 @@ Import a raw key string into Talos without rotating the credential. For the comp
IMPORTED_RAW_KEY=sk_preview_demo_001
RESPONSE=$(docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
keys imported import "preview-imported-key" \
--raw-key "$IMPORTED_RAW_KEY" \
--actor preview-import-user \
@@ -292,8 +291,8 @@ echo "$RESPONSE" | jq .
IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY
-export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
+echo "export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY" >> "$DOCTEST_ENV_FILE"
+echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
```
@@ -302,7 +301,7 @@ export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
```bash
IMPORTED_RAW_KEY=sk_preview_demo_001
-RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/importedApiKeys" \
+RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
-H "Content-Type: application/json" \
-d "{
\"raw_key\": \"$IMPORTED_RAW_KEY\",
@@ -316,8 +315,8 @@ echo "$RESPONSE" | jq .
IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY
-export IMPORTED_KEY_ID=$IMPORTED_KEY_ID
+echo "export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY" >> "$DOCTEST_ENV_FILE"
+echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
```
@@ -336,7 +335,7 @@ Imported keys use the same verify endpoint as issued keys. Talos detects the cre
```bash
docker run --rm --network talos-preview \
- europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.6 \
+ europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
keys verify "$IMPORTED_RAW_KEY" -e "http://talos:8080"
```
@@ -344,7 +343,7 @@ docker run --rm --network talos-preview \
```bash
-VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2/admin/apiKeys:verify" \
+VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-H "Content-Type: application/json" \
-d "{\"credential\":\"$IMPORTED_RAW_KEY\"}")
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
index d4b27218c3..efd9ab9d68 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
@@ -1,102 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "properties": {
- "requests": {
- "items": {
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "properties": {
- "actor_id": {
- "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
- "type": "string"
- },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "Additional metadata (OPTIONAL)",
- "type": "object"
- },
- "name": {
- "title": "Human-readable name (REQUIRED)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "raw_key": {
- "title": "The actual key string to import (REQUIRED)",
- "type": "string"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "Scopes for the imported key (OPTIONAL)",
- "type": "array"
- },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
- "type": "object"
- },
- "title": "Keys to import",
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchImportAPIKeysRequest"
- }
- }
- },
- "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","properties":{"requests":{"items":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"actor_id":{"description":"actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"},"title":"Keys to import","type":"array"}},"type":"object","title":"v2alpha1BatchImportAPIKeysRequest"}}},"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
index 96d6267bfd..cd904284dd 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
@@ -1,185 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
- "properties": {
- "failure_count": { "format": "int32", "type": "integer" },
- "results": {
- "items": {
- "description": "BatchImportResult contains the result for one key in a batch import request.",
- "properties": {
- "error_code": {
- "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
- "enum": [
- "BATCH_IMPORT_ERROR_UNSPECIFIED",
- "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
- "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
- "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
- "BATCH_IMPORT_ERROR_INTERNAL"
- ],
- "type": "string",
- "title": "v2BatchImportErrorCode"
- },
- "error_message": {
- "title": "Human-readable failure reason",
- "type": "string"
- },
- "imported_api_key": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": {
- "format": "date-time",
- "type": "string"
- },
- "expire_time": {
- "format": "date-time",
- "type": "string"
- },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": {
- "format": "date-time",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- },
- "index": {
- "format": "int32",
- "title": "Zero-based index in request.requests",
- "type": "integer"
- }
- },
- "type": "object",
- "title": "v2BatchImportResult"
- },
- "type": "array"
- },
- "success_count": { "format": "int32", "type": "integer" }
- },
- "type": "object",
- "title": "v2BatchImportAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "Batch import completed. Check per-item results for individual status."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysResponse returns per-item results and summary counters.","properties":{"failure_count":{"format":"int32","type":"integer"},"results":{"items":{"description":"BatchImportResult contains the result for one key in a batch import request.","properties":{"error_code":{"default":"BATCH_IMPORT_ERROR_UNSPECIFIED","description":"BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import","enum":["BATCH_IMPORT_ERROR_UNSPECIFIED","BATCH_IMPORT_ERROR_INVALID_ARGUMENT","BATCH_IMPORT_ERROR_ALREADY_EXISTS","BATCH_IMPORT_ERROR_FAILED_PRECONDITION","BATCH_IMPORT_ERROR_INTERNAL"],"type":"string","title":"v2alpha1BatchImportErrorCode"},"error_message":{"title":"Human-readable failure reason","type":"string"},"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"},"index":{"format":"int32","title":"Zero-based index in request.requests","type":"integer"}},"type":"object","title":"v2alpha1BatchImportResult"},"type":"array"},"success_count":{"format":"int32","type":"integer"}},"type":"object","title":"v2alpha1BatchImportAPIKeysResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"Batch import completed. Check per-item results for individual status."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
index c4846366de..fd0bb12661 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
@@ -5,30 +5,44 @@ description: "Imports up to 1000 external API keys in one request. Returns per-i
sidebar_label: "Batch Import API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item succeeds, response is 200 OK.
-If all items fail, the endpoint returns a non-200 error.
+Imports up to 1000 external API keys in one request. Returns per-item
+results. If at least one item succeeds, response is 200 OK. If all items
+fail, the endpoint returns a non-200 error.
```http
-POST /v2/admin/importedApiKeys:batchImport
+POST /v2alpha1/admin/importedApiKeys:batchImport
{
"requests": [
{"raw_key": "sk_live_abc", "name": "Stripe key", "actor_id": "user_1"},
@@ -37,12 +51,31 @@ POST /v2/admin/importedApiKeys:batchImport
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
index aaea5e239f..02f3db934e 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
@@ -1,30 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "requests": {
- "items": {
- "properties": {
- "credential": {
- "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyRequest"
- },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchVerifyAPIKeysRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"requests":{"items":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2alpha1VerifyAPIKeyRequest"},"type":"array"}},"type":"object","title":"v2alpha1BatchVerifyAPIKeysRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
index fae100dcd0..2097ba0f0e 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
@@ -1,125 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "results": {
- "items": {
- "properties": {
- "actor_id": { "type": "string" },
- "error_code": {
- "default": "VERIFICATION_ERROR_UNSPECIFIED",
- "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
- "enum": [
- "VERIFICATION_ERROR_UNSPECIFIED",
- "VERIFICATION_ERROR_INVALID_FORMAT",
- "VERIFICATION_ERROR_EXPIRED",
- "VERIFICATION_ERROR_REVOKED",
- "VERIFICATION_ERROR_NOT_FOUND",
- "VERIFICATION_ERROR_SIGNATURE_INVALID",
- "VERIFICATION_ERROR_INTERNAL",
- "VERIFICATION_ERROR_IP_NOT_ALLOWED",
- "VERIFICATION_ERROR_RATE_LIMITED"
- ],
- "title": "VerificationErrorCode provides type-safe error codes for verification failures",
- "type": "string"
- },
- "error_message": {
- "title": "Human-readable error message (only set if is_active=false)",
- "type": "string"
- },
- "expire_time": { "format": "date-time", "type": "string" },
- "is_active": { "type": "boolean" },
- "issuer": {
- "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
- "type": "string"
- },
- "key_id": { "type": "string" },
- "metadata": { "type": "object" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "rate_limit_remaining": {
- "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
- "format": "int64",
- "type": "string"
- },
- "rate_limit_reset_time": {
- "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
- "format": "date-time",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyResponse"
- },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2BatchVerifyAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"actor_id":{"type":"string"},"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"issuer":{"description":"The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.","type":"string"},"key_id":{"type":"string"},"metadata":{"type":"object"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1VerifyAPIKeyResponse"},"type":"array"}},"type":"object","title":"v2alpha1BatchVerifyAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
index dea1c3eaeb..4a3e646ee6 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
@@ -5,30 +5,44 @@ description: "Verifies multiple credentials in a single request. Efficiently ver
sidebar_label: "Batch Verify API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: eJztWF9vG7kR/yoDvtQOVrKTOwQHFQWqOHK6ic9WZSXXaxToRruzWp655Ibkyl4YBvoh+gn7SYrhrv5LvuDahz40D7GW5Azn72+G8yhScomVpZdGi574RFZmkhwUlfKyVASJpZS0l6gcSA0ITuq5IrD0tSLnuzDIMplI0l7VsFiSV+VEewMvz893GZRoUSlSXRhgkm/sgnRL+hSkTqkknQa2f5zoEm04k6FUlSUHaFkEX1lNaRf6acGyJQk5B0arujvRE/3LL7/k3pcTPby5HcPZ4hWqMseXZ8inz7CUH6h2vRn6JA961xP9ONEAE9Eq5yaiB595CeBxItay8vpEuLupkgua4ix5+eq7brc7EU/R0dNUv89n7xJ5I99f/n0wGv/1Nm5ImOLLRD8FgUUkTEkW2R9xKnoiqPZmLWN/GLPYIloK+cakteg9isRoT9rzTyxLJZPA4+xXx459FC7JqUD+VVq+wUty/LVUlX9LT4XbP7LWhL+89IpYsGEMd1SDsZCSlQtKwZs70nCCuobM2AJ9D9zd9EUE738aR1BggtYYfSoi4euSeThvpZ6Lp6fVipn9SonnE+01S69taj9qZBZrMrQW62/is2/KFTcmZ3NIS6noeVtRJB46xsq51KiGaLG4xoKZzdjm4bQrjXaNmV6dn/9HfnCVetYNmHhjpzINTti2XyTIWmOniUmJt1PKsFKeE3owii/ji/44vrmeDkajm9H04/XtcHARX8aDtyLayf8OPE/Qg2sD4S44YedzzqKS6elEw0Ha+PpT/yp+O728Gf3YH/fgYp3vTYgwC6kDk2M8Bn8bxiO+e4M4Rwf0ULKrjpGNBp9uPhwgmxFpsLQwd8dpr2/G08ubj9fb1Np4yEylGZ8gRY8zdHSMxW387ro//jgaLG3ArOrSm7nFMpcJODnX6CtLLew1gRIg7rhg8fV4MLruX/Ug1p6sRgWO7IJs65W04ojY4niU1TCo2b+6uvmJzdTmAcRD9gnrKjX4nDjL/+AAlTL3lMJF/HYEFvWc3FHL98eD6VX8YzwOfNETKFlID18r4xHoIcfKeUrhJDFFQTaRqDoM2wwNpKtC9D7/duT+ZrQdPtNG0+HNNmYOb66C4vD2nsOPydh48MjullOOCLlhXvFlDXGfNpw+4Gi4MClBac1CpuSAMaPjMKM2VBgsHGfhfvxxid1H6SXKFOQczmmzGPylKlB3LGGKM7W8oD0HJ+xacORBZiDdFBMvF/SnDJWjA8UgEk1iT70swiUNUIieSNFTJ6weIFox3sDHmTGKUDfbriLbgOMm4o1zgsToTM4ruyphzeFgG59LxzbkctKFy91q5+Dk/U/js1VtiyY6UBRcZtjoOTE3SBTKAqiYUZqG/ibsrPqdwKt7SK07qo9hfkEeGYU2Ntuyx6UJPU1D1k1Lo2RS76vOiXnFJ4bhADS7s1Zqu07bhkEwB2poC39osWINN7e3UJiUotZUzdmA6o3jpGGUQp1CQag9eAOzYHNXFZTCrJ7oqnTeEhYwR0/3WDs4GeiFqSO4UKZKM4WWIiCfdE+DFMSsEypI+24QYo0jrSxjVMYtz7kNZRxU3MGC1J2CCmNDAzOiVDqYYXJHOnXRRM+Mz6E092SDhMEg7y5GfTh5R5qsTOCClGqgra/mxkqfF6fBJBemKJVkRe+lzyG1mPmOJJ91uBnFUnZYmCBLJydMybrOy3P2/Xa5D1i577QGQmXjI10VM7JgsmU7vobpkizcS52ae2a9SiGp/evvD8VZpaXfzGj+3omI5uqwweTdiX7b9Bm9rZZ5om98TrZpDPj/ilwQJx6ML8GVlPD5tk3qzGpPbiKiZimprOXVNbdDsjZ67dumWV8ah4GiNUGbya0K3eCkwuhWuB68Pndw8hIKqStPpxF89/q8WclNZU8j+OH19+1CivXpgTz9hsZzJ9t2ctRSgVIzrz2t+mVpzYMsONYOOXyBUgXUnVFmLO0mr3RgCZOce4rdehvBCprvc9KbecV0DZ6eflsAbSnjyK/gewdvg1f4sm05ybbvOccAkVVKQYIlJtLXcIJKtdFnKTELzsptqZ6tDC4xJW131ntntt8RkVhIJ2dSSV9v99MfBj9PP8W38Zv4Kh7//Gwv/YHqTysukErnpZ5X0nFZKKuZkgmcJIpfzqEqnzKoOsisKcBRYsnDSdPaNa1R2O5O9LAhDYcrR4CQyiwjTptVIQvhUFrK5ENT4KWrULUyJCxfd6LfMMax3g5cjm3gOCwIgsHOSrKFdI57Alc7TwX86x//hLVhQoTMTOW5ETeOG1nWwzeVATpw3FY9GFtC7gDRwe3gYjQYb3R+z9p4Z3NFvLM+/PjmKr4I3dGWq/fzcstNv+Mp2rwA/2tv0SU7pt/BAXBVmHBklYLly7Mrwrk2PH/363P5cNxM8+9erZNJak9zss1lHqXaTidMU9nU+eEm26fdmvbnht1e/j1jq9Iab2ZV1tf1oTzd7EW/mactk1uPvnIHzayh0vRQUsLx2XSyG9Zmtjh3HKfMQybr96HjcCvI54YHN6VxfGeJPhc98Q3TJxEJdtNoPdYZPGBRKtoe03zeHsis9P3CTa7OzD7k3ti67Yc4YyGX87xTkg2+1gmBC3psjuIK1DhvygBDkEyoC7GHHHWq2magQeg1iZIZJXWiqBe6Z26xGKKipset+dvnVAB6UOYeFHrSSR013TTvutxY31G7rXVoHH9ctdfhMzzemaaZ+AW84T6eO1PpwJWK6x4PIP29WWrgenysAy9e7PntxYsAbcEzsBq/uV6Yb60Ug5PwLIjAGo+e/4YZQgSyKI31rSrUCs9Drw+3p0He7dd4EIFUdtvI1V7uSGWdVtTAefkc45faxgDDKO4YN4J57d3+MBaRWJB1jd+XIcd5wtFYYMAA3cywAvhAE3rBcu1YcSt2NgDl/7Ph/4HZcItonh78WalQhqdtZcNgtkGaz2u3RyJow38PoM2XSOQMUb3P4vGRB1kfrXp64uWvFdla9D5/icQCreRmgr+eItG8VwIG3VEteuKi7eLHLBcfV1WA593S8xQtKfpJQqV/9uwmirJ7RNQMXHuPogh1Sli85wE43oueCBPzkK8BJzG8CxTqeRXqgmh48r9/A3o2oyQ=
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
-verified independently; partial failures are returned. Admin access only.
+Verifies multiple credentials in a single request. Efficiently verifies up
+to 100 credentials in parallel. Each credential is verified independently;
+partial failures are returned. Admin access only.
```http
-POST /v2/admin/apiKeys:batchVerify
+POST /v2alpha1/admin/apiKeys:batchVerify
{
"requests": [
{"credential": "sk_live_abc123..."},
@@ -37,12 +51,31 @@ POST /v2/admin/apiKeys:batchVerify
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
index 092cc31162..2a18929b0d 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
@@ -1,11 +1 @@
-{
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
index cd80ba989c..976062bed3 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
@@ -1,36 +1 @@
-{
- "responses": {
- "200": {
- "content": { "application/json": { "schema": { "type": "object" } } },
- "description": "A successful response."
- },
- "204": {
- "content": { "application/json": { "schema": {} } },
- "description": "Imported key deleted successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"Imported key deleted successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
index df644d5bef..6d34b16714 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
@@ -5,38 +5,70 @@ description: "Permanently deletes an imported key (hard delete). The key is remo
sidebar_label: "Delete Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: eJzdVcluIzcQ/ZVCnSyDthwlM4c+RYgNRDMJ4njBHGwjppvVao7ZZA9ZrZmG0EA+Il+YLwmKLdnyggS+5sS1ql5tr9ZoKJXRtmyDxwJPKTbak2fXgyFHTAm0B9u0ITIZuKce9modzeZ1cggXNeVrmyBSE1ZkoIqhufZcExjN+k4nOoTLRHBGq3BP89PFR+qhChFSqHjUZIOHvUhlaBryhszk8Npf+9vb25q5vfbHJ7+cXJzAdDWbatNYP90imrf2I/Vpur6n/g9rhiyDCkNLUYvWhcEC5yJznBEvtoIZBSpsddQNMcWExdX6WTzOf56/+242nb17D7VONYQKxK2n8Tg7+f1ycXZyPEGFVqRazTUq9LohLHBEhgojfelsJIMFx44UprKmRmOxRu5b+Zk4Wr/EYbiRz6kNPlGS99nRkSxl8EyeZavb1tkyezj9nATr+qW+cPeZSsZhGNQzv+aQurKklKrOwdbUIQ4KZ0c/vMXUK7oXu8EZy8TsmHN9tmOo0p3jN7nVRkkr2zEoZTAkaxVioxkLtJ6/n6Haem8905LiaIy1dVnKMjV5o42xYke70121g3pm5sdR3cskqWdhVsiWnVy0MXC466q57/Hxm45R53NDKenlG3XGtjxnzV16NZ0eOk/fWiol1hRjiLtZFbV6KfWNosOWP0Uy5Nlql/BGAHEdpE/GbOWm4BoL/O9+yyVfBfHlKaTfYg8X2oUkxKChtsv6oKWYk+VLgpSBQPmABBrt9ZIa8gyJ4sqWdAgLhlp74yjlvpPy2RVxtqKyLx0VYFPqrF9K0SUFK4q26uXMNTWgGVz4Ck4z+bJXYCjalbymOkQ+cFZYi8M9+QR7Hz5dgPYGftWljiH4icrHKOQlMjpXcuYn4b756UJcTK2zDNZzAP4ath6kQr4dwP7+i8Dv78Pff/4FObzwQFepyG3z4BjsiWOkIAbWLGvmULWhoI0rtAGv4MOnj+eTjDeHYNNLGwjkqvMR18Z4IlcdbKBmzeP3zM07Ya6DM8KPj9X4mN356QIVriimMe+zwyOp8TYkbnTu3w0NjvQLD+wgcRsZ+Enh7NDB/2cabZqa6RtPW6etlxB10WVSy612hSuhrqxOeuqpQlRYbMbIjcI6JBaJ9VqcuYxuGOT6S0exx+LqRuFKR6vvJFMy0WySvcGi0i7Rv8R772wzoSbw5sH3qotb5vOS5pV2nZxQyUh8HIzDzaCwJm0oZrzj47wsqeUdsRejYdhlrjElOAz/AAf+FdE=
+api: eJzdVdtu5DYM/RWCT5lAyWSn3T74qYMmQGe3RdNcsA9J0CgWPdZGlrwSPbvGwEA/ol/YLykozySTC4rmtU++SCQPD8nDNRpKZbQt2+CxwFOKjfbk2fVgyBFTAu3BNm2ITAbuqYe9WkezOZ0cwkVN+bdNEKkJKzJQxdBce64JjGZ9pxMdwmUiOKNVuKf56eIj9VCFCClUPHqywcNepDI0DXlDZnJ47a/97e1tzdxe++OTX04uTmC6mmnX1vrdVJvG+ukW17y1H6lP0/U99X9YM2RLVBhailp8LwwWOBeb44x7sTXMWFBhq6NuiCkmLK7Wz1g5/3n+/t1sOnv/A9Q61RAqkOSesnJ28vvl4uzkeIIKrVi1mmtU6HVDWOCIDBVG+tLZSAYLjh0pTGVNjcZijdy3cjNxtH6Jw3Ajl1MbfKIk57OjI3mUwTN5llfdts6WOcPp5yRY1y/9hbvPVDIOw6Ce5TWH1JUlpVR1DrahDnFQODv6/i2hXvG92CVnbBazE871OY6hSneO35RWG6WsbEdSymBInlWIjWYs0Hr+boZqm731TEuKYzDW1mUry9TkF22MlTjane66HdSzMD+O7l4WST2jWSFbdvKjjYHDXVfNfY+P13SMOn83lJJevtFnbMtz1tylV8vpofP0raVSuKYYQ9ytqrjVS+lvFB+2/CmSIc9Wu4Q3AojrIHMyVisPBddY4H+dutz4VZCMngL7LfZwoV1IIhIaarusD1qKuWS+JEgZDpQPeKDRXi+pIc+QKK5sSYewYKi1N45Snj5pol0TZysq+9JRATalzvqltF5SsKJoq16+uaYGNIMLX8FpJl/2CgxFu5LTVIfIB86KgnG4J59g78OnC9DewK+61DEEP1H5M4qQiY3O/Zy1SnRwfrqQFFPrLIP1HIC/hm0GqZBrB7C//4L+/X34+8+/INMLD6KVijw8D4nBniRGCmJgzfLMeqo2QrRJhTbgFXz49PF8kvFmCjYTtYFArjofcW2CJ3LVwQZq9jxezzq9Q3MdnBGVfOzJx+rOTxeocEUxjXXf9o20exsSNzqP8kYRRyWGB6EQ8kYxftI9O8rwf1tPmyln+sbT1mnrhaguuqxyefauHjlUmJ3KkD11iwqLzXa5UViHxGK3Xktil9ENg/z+0lHssbi6UbjS0eo7KZ0sOpvk3WBRaZfoX7jfO9ssrgm8eR++muhWEL2UfKVdJ1+oZFM+7svhZlBYkzYUM97xcF6W1PKO2YuNMewK2lgeHIZ/ANhyIPw=
sidebar_class_name: "delete api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Permanently deletes an imported key (hard delete). The key is removed from the database. Use RevokeAPIKey for soft deletion
-(recommended).
+Permanently deletes an imported key (hard delete). The key is removed from
+the database. Use RevokeAPIKey for soft deletion (recommended).
```http
-DELETE /v2/admin/importedApiKeys/{key_id}
+DELETE /v2alpha1/admin/importedApiKeys/{key_id}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
index 0fecc60986..c96fb965ed 100644
--- a/docs/talos/reference/api/admin-derive-token.RequestSchema.json
+++ b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
@@ -1,38 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "algorithm": {
- "default": "TOKEN_ALGORITHM_UNSPECIFIED",
- "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
- "enum": [
- "TOKEN_ALGORITHM_UNSPECIFIED",
- "TOKEN_ALGORITHM_JWT",
- "TOKEN_ALGORITHM_MACAROON"
- ],
- "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
- "type": "string"
- },
- "credential": {
- "title": "The API key secret (issued or imported) to derive a token from",
- "type": "string"
- },
- "custom_claims": { "type": "object" },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- }
- },
- "title": "Token derivation messages",
- "type": "object"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"algorithm":{"default":"TOKEN_ALGORITHM_UNSPECIFIED","description":"- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)","enum":["TOKEN_ALGORITHM_UNSPECIFIED","TOKEN_ALGORITHM_JWT","TOKEN_ALGORITHM_MACAROON"],"title":"TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken","type":"string"},"credential":{"title":"The API key secret (issued or imported) to derive a token from","type":"string"},"custom_claims":{"type":"object"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"}},"title":"Token derivation messages","type":"object"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
index 7b33c4812d..167b2a0766 100644
--- a/docs/talos/reference/api/admin-derive-token.StatusCodes.json
+++ b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
@@ -1,51 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "token": {
- "properties": {
- "claims": { "type": "object" },
- "expire_time": { "format": "date-time", "type": "string" },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "token": { "type": "string" }
- },
- "title": "Token represents a short-lived derived token (JWT or Macaroon)",
- "type": "object"
- }
- },
- "type": "object",
- "title": "v2DeriveTokenResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"token":{"properties":{"claims":{"type":"object"},"expire_time":{"format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token":{"type":"string"}},"title":"Token represents a short-lived derived token (JWT or Macaroon)","type":"object"}},"type":"object","title":"v2alpha1DeriveTokenResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-derive-token.api.mdx b/docs/talos/reference/api/admin-derive-token.api.mdx
index 5ab852e102..56d2d8a202 100644
--- a/docs/talos/reference/api/admin-derive-token.api.mdx
+++ b/docs/talos/reference/api/admin-derive-token.api.mdx
@@ -5,42 +5,75 @@ description: "Mints a short-lived JWT or Macaroon token from an API key. Works w
sidebar_label: "Derive Token"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys. The derived token inherits
-the permissions of the parent API key.
+Mints a short-lived JWT or Macaroon token from an API key. Works with both
+issued and imported keys. The derived token inherits the permissions of the
+parent API key.
```http
-POST /v2/admin/apiKeys:derive
+POST /v2alpha1/admin/apiKeys:derive
{
"credential": "eyJhbGciOiJFZERTQSI...",
"ttl": "1h"
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
index 092cc31162..2a18929b0d 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
@@ -1,11 +1 @@
-{
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
index b6035db77e..7c2e8fbd5b 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
@@ -1,125 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
index facf37bc9c..96186e7886 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
@@ -5,37 +5,70 @@ description: "Retrieves details about a specific imported key. Returns metadata
sidebar_label: "Get Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Retrieves details about a specific imported key. Returns metadata about the imported key. The original raw key is never returned.
+Retrieves details about a specific imported key. Returns metadata about
+the imported key. The original raw key is never returned.
```http
-GET /v2/admin/importedApiKeys/{key_id}
+GET /v2alpha1/admin/importedApiKeys/{key_id}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
index b19b7ceb16..d3b3282f04 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
@@ -1,10 +1 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"UUID of the issued key, taken from the path\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
index f922dc595f..fa372beabf 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
@@ -1,122 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
index ba08065ba6..8c6c6fe50c 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
@@ -5,38 +5,70 @@ description: "Retrieves details about a specific issued API key including its st
sidebar_label: "Get Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Retrieves details about a specific issued API key including its status, scopes, expiration, and usage statistics. The secret is
-never returned.
+Retrieves details about a specific issued API key including its status,
+scopes, expiration, and usage statistics. The secret is never returned.
```http
-GET /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+GET /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
index 07c363956d..37773d0b3d 100644
--- a/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
@@ -1,42 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "jwks": { "title": "JSON Web Key Set", "type": "object" }
- },
- "type": "object",
- "title": "v2GetJWKSResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"jwks":{"title":"JSON Web Key Set","type":"object"}},"type":"object","title":"v2alpha1GetJWKSResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-get-jwks.api.mdx b/docs/talos/reference/api/admin-get-jwks.api.mdx
index 628ed39882..c488c5db43 100644
--- a/docs/talos/reference/api/admin-get-jwks.api.mdx
+++ b/docs/talos/reference/api/admin-get-jwks.api.mdx
@@ -5,34 +5,64 @@ description: "Returns the JSON Web Key Set for token verification. Provides the
sidebar_label: "Get JWKS"
hide_title: true
hide_table_of_contents: true
-api: eJztVc1u4zYQfpUBT0mg2Knb7gI61VjsBs6i3SD2Igc7QGhyZDGmSJUcKSsYBvoQfcI+STGUEjvpYotFrz3xRzPffDOc+bQTGqMKpibjncjFDVITXAQqEa7mn36DW1zDR+xgjgSFD0B+iw5aDKYwSrLXCK6Db43G3qtu1taoldtiF8EhatRAvvfo4Op20UNEMDE2qGHdAZUmQsTQGoUjjhZBBgTrpUa9ckXwFSjvCrNpQgoJJ4WxmI/HGZREdUw7H2AtI775KR+P4fPNLJ6O4IO31j8mYit3dftxDpGk0zJoOLn58A7e/vzD29PRyq3c/f09Q63c5fsFjNvJWOrKuLHGYFrUzGn88LiNo4foe2uRCV9jz2emRS6m7HCJxGFEJgLG2ruIUeQ7Mbm44EV5R+iIt7Ku7VDAMWPyXVQlVpJ3dWBsMr03B+aVDFkUuXj9MCIT1NX8xa8fUJHY71/fZM/O7WTgeDMQFHs2f9kGU4iNUhhj0Vh4ymQkkl0hG0v/IRvlNfJa+FBJErkwjn6cHHIwjnCDoQ9G0tjkZQirtJFaG44j7fUx7D57FeaXHm73BBspGLf5Zmnq4Mmvm2LqOnEwkyHIdK4wRrn5TsxQqzlJauJXy+ygcfilRkWoAUPw4bjaDCs3UeRLwRhGvQuo0ZGRNoo7JkSl59bbpB6oJZUiF//SvCITxhWes3hJ5lPoYCGt58kECaXZlOc1hvRMTiFPDhkF6pkDVNLJDVbo6DC9M4JSOm0HNSgaa49drClQdcpinubfuA2wUGSDPvCZSqxAElj/CFYSOtVlkFLhr7H0gc4t5/UkJCcsKtJp+FUqGbx3p1k6Bmz9ln1kauU05osSYXo94xRjbQ2BceSBHv1TBjFns3M4O/tHyc/O4K8//oRUW3ie/ZhzBofE4CQJWwbBkyRemQZmYKraBxpSwYF8BjyKp4nvsagOFNAW857XEDyiLc4Hqgm5N0/SfFTm0luNIR714eF1p9czkYkWQ+zffTK64O6ufaRKpsl1smKXSyQYxOxFpxxN/v//i+/5XwwaQfiFxrWVxnHdm2CTRqbhXYqWlTBhpbI/o4lMHEb4LhOlj8T2ux0n8TnY/Z6vf28wdCJf3mWilcHINT/+8m6fiRKlxiDy5U5ssWPxUQpr1o1W2iYJ3WsR3x9rzOX7hdjv/wayxNug
+api: eJztVdtu4zYQ/ZUBn5JAsXfTywJ6arDYDZJFu0GcRR7iABmTI4sJRarkyFnBMNCP6Bf2S4qh5NhJi6KLvvaJlMRz5sxw5mitDCUdbcs2eFWqK+Iu+gRcE1zMPv8CN7SAT9TDjBiqEIHDI3lYUbSV1SioCVzGsLKGBlTbLZzVc/9IfQJPZMgAhwHRw8XN9UCRwKbUkYFFD1zbBIniymqaSLQEGAlcQENm7qsYGtDBV3bZxRwSDirrqJxOC6iZ25R3IcICE/34fTmdwper83Q4gY/BufCUhc39xc2nGSRGbzAaOLj6+B7e/fD23eFk7uf+/v5eqOb+7MM1TFcn6Noa307RNNZPDUW7IiPKpg9Pj2nykMKAUYUKLQ2qzo0q1akAzoglmCpUpNQGnyipcq1O3ryRRQfP5Fm22LZuLONUOOVd0jU1KLs2CjfbAS2BZWXLjlSpXl+PKhT3rXwJiwfSrDab12+KZ/A2wVHp1ShTbQT0siVOIXVaU0pV52Cbz0TlcxV2jv9DTjoYkrUKsUFWpbKevzvZZWI905LiEIzRuoyyTE3eoDFW4qC73KfdFK/C/DTQrbe0iaP1y38sUBsDh0VXnfpe7Y5hjJifG0oJl9/IGVs9Y+Qu/W2ZPXSevrakmQxQjCHuV1tocZlUeauEw+r3kQx5tuiSuhNBXAdpwGXuhBa5VqX6V42sCmV9FSSXl5I+xx6u0QWZVUCo7bI+binmy/KaZJbYatDPSqBBj0tqyPNuns8ZavTGjf5Qdc7tQ5ytSPfaUZkdwfoliHUUo2PIM9fUADK48AQOmbzuC8ipyNdUh8jHTvLaWsuB2Ax6Az+jxhiCPyzyY6RVeBQM5obOg39dE5xenkuKqXWWwXoOwE9hm0Eq5dgxHB39pfBHR/DHb79Dri08+0AqJYNdYnCQra6AGBhZVpFBBdimDZHHVGgUX4AM5GHWu2+zowRy1WzQNQZP5KrjUWpmHo5ns94rcx2coZj2unF3u6eX56pQK4ppuPdt00ijtyFxg3mIPTaCOyOG0d1etMueCfz/G/n238hoGkxfedo6tF6q30WXTTNP8+3uYgqVGfMVPHOqQu1m+q5QdUgsqPVaEvoS3WYjr3/tKPaqvL0r1AqjxYV0w+3dplA1oaGoytu1eqRePElrasVOVui67H+vvX2zbz1nH67VZvMnSYXpAg==
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
-
+
+
-
+
+
+
-Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
-Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
+
+
+Returns the JSON Web Key Set for token verification. Provides the public
+keys needed to verify JWT tokens issued by this service. Keys are loaded
+from configuration (file://, https://, or base64:// URIs). Follows the
+JWKS standard (RFC 7517).
```http
-GET /v2/admin/.well-known/jwks.json
+GET /v2alpha1/admin/derivedKeys/jwks.json
```
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
index 0d8212aaf6..23a8a35c96 100644
--- a/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
@@ -1,91 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "properties": {
- "actor_id": {
- "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
- "type": "string"
- },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "Additional metadata (OPTIONAL)",
- "type": "object"
- },
- "name": {
- "title": "Human-readable name (REQUIRED)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "raw_key": {
- "title": "The actual key string to import (REQUIRED)",
- "type": "string"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "Scopes for the imported key (OPTIONAL)",
- "type": "array"
- },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
- "type": "object"
- }
- }
- },
- "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"actor_id":{"description":"actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"}}},"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
index 171404d5ed..180fa3c667 100644
--- a/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
@@ -1,135 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "imported_api_key": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- }
- },
- "type": "object",
- "title": "v2ImportAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key imported successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}},"type":"object","title":"v2alpha1ImportAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key imported successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-import-api-key.api.mdx b/docs/talos/reference/api/admin-import-api-key.api.mdx
index 4bf6b63c79..3c099bbdca 100644
--- a/docs/talos/reference/api/admin-import-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-import-api-key.api.mdx
@@ -5,30 +5,45 @@ description: "Imports an external API key into the system. Allows importing keys
sidebar_label: "Import API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: eJztWuuO27oRfpWBftmB7LV3s3tSFwXqOE6ik8u6tpP0IAp8aGlssyuRCknZqy626EP0Cfsk7ZCSLV9yK9Af7dksEFjUaDgznPnmIt15MepI8cxwKbyeF6SZVEYDE4C3BpVgCfRHAdxgAVwYCWaFoAttMG1DP0nkRgO3z3CxJCoNCyXTUCS4ZFFRkmqQascvU3LNY1S6DdMVgmIbx17DiukVxrDhZhWKyct+67J7fnZ+eQVMxCBFUtjtiYqotZEKY/jn3/9hl2t8BK5RgULDuMC4HQqnFsZOQp1ndAlG3qCAGBVfM9IfGj9/mJ69YRFTUoomJPwGgWudlw+2QxGKX3/9dWVMForR9WQKZ+tzlmQr1j1jccrFGS836mf8FRY6FHehAAg9xTazGyxCrwehp29mCV/jjM2j7vnFbfHX0PMdmWApOpqtxBOjeIbwih4uqVhkpJrx2FHmGtWse34ReqG4t/J5viczVFanIPZ6Xp9kcxz7o+AVFp7vKfycozZPZVx4vTsvksKgMPSTZVnCI/v02V80ucWdp6MVpox+7fvL8JalWYI9Esyq+m1lf3ryu1KTfY1LRUdKxnlkj2On87HWGStSFKaVKRmh1lLVKHUkM9RE9zH0FLI49HwIvY3iBkPv05bOmMQxe/LTVWdFRHB2Bl0okClosERLYFGEmdE9uOheXlx1Oh3drJ5O0bCYGUYs7kJPy1xFpSraquJ2RbHmSgoStpR8q2Do3ROze8+nxQyV4ajtCZSqHtu7ukNeTk7PYxSGLzgqkAu7QteGAoUZkBtBZLyKUefH7VCM8XPOKXi0BIqVYo/AMlcsQjZPEIwkNLAbw0JSWK2l8w4Ky1CwPOYGPueoOOq253umyNDrWSOIpXfvezybKaTLyGlxqFQwGu9uQ4wLLlBDMGrNmcbYnoHWQB6qZKKtEExUsNQOxYcVCmAERhjPIh4rbUFAihammSl8Bx2lwzuAgmCkIWUmWhFuMQMJMm1ACgzFIHg2BsXEEoEphAxVyo3BuA1DYnewU4pM0GYQjKCmJflPYncpyZsEQ3skGijSCjKwktJscZbAbu841qj4ooxIq8vvQ2FRC2OHYdohV7pFLpJbG2YwIcsRQyEN6Hz+F4wI90jYaIXRjT2wA+erq3fCAw/tzCDhZLoF7Aynnf+RGCU9bZprdN7ojm3iYFjDXJoVBKP1Y2hge9mmqOl22vbv7EnoNa0CwWh9tbt/3ul0e/H8Sa93dnEeeta4CyiPe2v52vYNIeu2b5LenFITaXjkseUCU4oV3v1uQVoDko9zk9BCBf97LkwcKnSw7Evifhxzus8SqG5D43o0Da7f9l83vcNd7n2LjnUOL/OUiRZBmg1Nug2N8fBP74Lx8FnzVOwpZnCW8JSbWSYTHhXHJzpmBl8TxcgSgLs7R12mVYNgGYBjcBx/oQgEXE8mkMoYfXfEJS1Bj1hIlbJScTpKChnrhXOkqNZ5+u80Pi9CkWfaKGQpLJnBDSs0NIZiLQsfBonM40XCFPqAJmo3rRRIrCMkbG1bISKZpqgiTha2skxZInVFp2vKaMg1hT4XrRRTqQoqUcYYcw1zFt2giLUfCuuZmdygshJag7wYjPvQeIECFY9ggEkCZEHoJ0upuFmlTWuSgUyzhJOiVM5ArNjCtDiaRYvKB5bxFgljZWmtkFE91Op2jsPxcy7NicRrl6ssIPJ07jLAFuQqv89QwYaLWG6ItTsJr+dxYa4en/KXXHBT9zi6PvAIt7W9QY+3Q/EMFyxPDGW3SgCqRq7NChWsWcJj+j9HbcUJhtPnoDOMiL6sO1rzwlDK9t1SlCtFqztup2R1eh3bxq1XxjE8xdIE1mm2KrTtIaVSlML14KqjodGFlIvcYNMHyvh2ZSVz1fThydXjciFmRfNErvsOpDiINhejtl6qm50KYxaZnCU2Azj+FDIuMXwr6J3Zygqi4jlIONm0zKMJxlQ9pJk0KKLCbtPoB6NW9/LyJFNXVRHDr+BmudXE0m7NvZfNTiFeCbQ+lWTH52lMAhqNO068zbgqgFHiiXNX5LqULuSmHYq+rdgwBufr2pamLRjeGhQxxuRz3SL0oHFxdRk3ba5Jpb3ulJcbuvqpvIjp4vzxqunYTAwTMVMxvJDE6fzxyvnsRSd1P646pRd3V3bNPUZgIHNR7n5FGzru3fOSwfnmIibqfpYpecsdXuoedAv4A1xcXZLHaR+6qaTrjr10SS8XGo1vbZMpaRN87OIRptPXtsagwgzesFue5imFxd+6HVvkamhUdW1Hn/Jn31tzzec84aZMHJax1/NeDX+ZvQ8mwdPgdTD9Zfbu7WQ0HATPg+Ezzz84vldYvN9ygZhr6hVzrleEB/k84RE0Iuebmi2wuWsjQWOk0EBDo1qjalHt06xasZF71BJTZcEg5osFEm5QVlnwZa5slswULvitdcY11xRSTgabq9uheEogT4pr0CuqGWyPS6nVuvyZLQC1Jj9z7axtOXeGsUXQXOaGfFPqnGovtkDjUiO04Mu26sFUISNvZRomw8F4OPV8D0Weer2PX7fxwc3twwfro3dPXwcD79Ph0R4D094xOSgrKeqd49hBSxnS+4OCl2/6g7JmL4uD45qG+D60kP+NFlKVPZ3XMypH37ttScWXXLBkxBRL39pS0ptTv29ThM6k0A7QzzudH5oB7FcoFbrPWMarPHZqqoSxcyFQmCnUKJz7bMdLVZKwkV/3q3LeFIrT46JGbVLkegU3GXLjpcoIX5gNfbX3PkLDyEbrjEoKur8tp2JmsGVXT0CozVg/+tBDz/zQM//WeuYbLA5K1voM2I595QIihXboxZJTcZMwbWa5xvgH422vX/9iG/7QXT901w/d9f9Yd72dV8/2FDnU6zRd9baKUiBii47YZlW8NS5Ua/PwdiiuKWtqNLCh/FpjqZBpKchqo3HwPng9fDGcfQimL5+N+x/etkPx8+T6rQ36aEXJoAcLjkkMG2Zzd4rKZuMDdjMSow3PLWnppt2LUHANuXCM7IifDsVdkgAbrrAVyTRjhlN/RGrMuWCqIGWNBBSRjLlYnmwIj4TY7wvHw/fXgz41+LPxsD+5fvvV1nC8ZTZ29tlaWxuVRyYnZKi9cHA7EurpjJeoMX4+gMvzJ512KN5R6cOFS472hZwrBzFZtGpcFvTasmrOjgU+cUA9sK/QbAPas3VBhQBcHLKvNXDfMsbxfereBtdvRuPrN8FkeJKk//x58DpwS4OX/bcvvsBq8m40HE+Gz75w+4SW39MlHp7Yd0+GDgY9VGnl+nimMJn2p+8mB3aqN8QnCWo3+oNp8H64v0bavzokHP55RAO072yNJ05ewvAs/vEe4GGM8hseo3yrDt7rjn/gkWoi4zr5U7OVPujcdoKLPIGq5W+TQ553uj/S8p/ifdi377ZKCrvH1s3/49FCJOP9IOPCXJzvAowLg0tUbjPDeLKPQmz7wm1UZ3t/WAX+0bE7gq2vnITNlPN80RfFKXhLUWu2/EGeKosqmDlhbgG5wNsMI7I1KmVfxW9PlNiypSZ/Jx48GmzbJE1um6JZSfoWJJOa9syYWXk97xvfr3i+R0c03n0rUk7r9iclu2g4HlsctMYfK9pP+03Xtsva8TrZXJUF+47KldS766ps3evSyvcrNd61NyS71SqR7YQs30jsSOpA/jVkoRGOWMjjMvNaFWXfZOcAK75ctTJU1sNF5EYQPKp1uZAywZa2DQMCcB5hGwIDKybipGwaKObqjyR8gVERJdiz3y9V32b5bixS2HdJK0ztEEduIGH2HZDvvoWiu3ollWklh+MSW05tP5Dy7SVVPjd2ImTD36I1Dd4IH+grrSzhpvx2bCMrDei1TCha8OjRkbc+emQTgyvftt8x6Z4Fm61i0LAfZvmgJM1sfCcG+iUclapgKbwPP394NXFDkfpkqBQBk8XEyVVubku6UtR6/UnJr2bmlUyos6yF8O50+6OA3AWVdudeBRp5BsVgymx4lE7vAN3azH2eddCqbPHz4Qu9/5Mv9MokQB3cWZYwbivpXNnXnw6cP+58xves8ASwBwD9yfdWhOi9j97dHc1+36nk/p6W6Yuswut9/OR7a6Y41XB0de97biDi9T7eeQ4WB+WYYEoyEXmS22x2mKnv/eoJ95b1q7T1pEMn4fnu5UPvzkttWieTW5gntLbfLNpAJwK7duclTCxzm0Y9x5P+/QuxtrSB
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is
-hashed and stored securely (HMAC). Imported keys support token derivation (JWT/Macaroon) like issued keys.
+Imports an external API key into the system. Allows importing keys from
+legacy systems or external providers. The raw key is hashed with
+SHA-512/256 and only the hash is stored — the raw key is never retained.
+Imported keys support token derivation (JWT/Macaroon) like issued keys.
```http
-POST /v2/admin/importedApiKeys
+POST /v2alpha1/admin/importedApiKeys
{
"raw_key": "sk_live_abc123xyz",
"name": "Imported Stripe Key",
@@ -36,12 +51,31 @@ POST /v2/admin/importedApiKeys
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
index 11096ba113..8025b5c876 100644
--- a/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
@@ -1,72 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "actor_id": { "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "request_id": {
- "title": "Client-controlled idempotency key (AIP-155)",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "ttl": {
- "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssueAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssueAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
index 2cfb37410c..2d3f09ef04 100644
--- a/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
@@ -1,136 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "secret": {
- "title": "Only returned on creation",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2IssueAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key issued successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"secret":{"title":"Only returned on creation","type":"string"}},"type":"object","title":"v2alpha1IssueAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key issued successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-issue-api-key.api.mdx b/docs/talos/reference/api/admin-issue-api-key.api.mdx
index 0d2b092b6e..efce5124b5 100644
--- a/docs/talos/reference/api/admin-issue-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-issue-api-key.api.mdx
@@ -5,30 +5,44 @@ description: "Creates a new API key for a given actor. The secret is returned on
sidebar_label: "Issue API Key"
hide_title: true
hide_table_of_contents: true
-api: eJztGtuO27j1Vw745Alkjz2TzAYuCtRxnKxymTFsJ+kiCry0dGxxI5EKSdkjDKboR/QL+yXFIeW7M9tsHwq0kwECkzw6PPebdMcSNLEWhRVKsi7ra+QWDXCQuILeMISvWMFcaeCwEEuUwGOrdAsmKYLBWKMFYUCjLbXEBJTMKlAyxkgKCTZF0GgKJQ0ClwnEXEplYUbbVgtcYgIZt6hb8BYrQ+d0aGJVYAIrYdNImgJjMRcxFKhzYYxQ0jhkKV8iKEc5zwBvC6E5LVqRjOSvv/6aWltEcngznsD58uKcJ7mQ58KYEpNeIei+SN5FEiBikucYsS5ErNAqKWNC0zSolyLGiAUeyHE+FYkHLA3qaeficnPsiDZ0+DliGnkSsQAittLCYsS+1FDWZv755z9dtdOIRfLeEcsCpgr0DIQJ67IekRsStb1h+BYrFjCN30o09oVKKta9Y7GSFqWln7woMhG7h89/M6TJO2biFHNOvwpNqK1A42BrNui3rQpkXWasFnLB7gMmiqlGWsbeIO4O7CMcjrbHkOBcSDQQDpszbjABHsdoDBBlWmXGG45c21Erkp9SMqEsUytMprFItCHzkUo2MS9sFXgDqhk1MNcqh3BoIOc2ToVcALeQITcWlMRI9sOXI9BcLhC4Rm8h1mLSggGhO7gpRy7pMgiHsMMlNHiWuVtq8LNWJPdBDJCEK7AKtFJ24xhkhiIvlLaYuI0larJVpwnHy58imaAWZOhWfUVpoPHm0+Q85zHXSskzR7ex3GJGkiOE5CGmnP2GsaULwyHEKcZfTYsFh6rcZe9YWUdy5pAJEt0ctoIzYFNuHRk1PF1aGgSbClOrbVwWxKSBmbIphMPlU2hga9EiA++0W+7v/HnEzhwD4XB5tT2/aLc73WT2vNs9v7yImBPuHGp1byS/c31Dql3ZnxHfwmJuTlpsvcG15hW7324oJ0AWMCtsRhvLiz3jpWdztDzhlu8grh+7D1xMOHmj5hanmciFnRYqE3F1LPkRt/iOIIYOAPzpzAkbgRCAQwAewbGfRDKUcDMeQ64SDLwqalhhQMi50jmvIx+JnEzbWcsMyftMmWMCsyqSZWGsRp7Dgltc8cpAYyCXqgqgn6kymWdcYwBo49aZowIJdYw5SttyRMQqz1HHgmc1LROeKbOGMzvMGCgNuaiQzRxzpStQGkaYCAMzHn9FmZggks6CCrVC7Sh0AnndH/Wg8RolahFDH7MMSILQyxZKC5vmZ04kfZUXmSBGKTNAovncNgXaeZNCPS9Ek4hxtDRT5Alq0+y0j93mW6m8zveV5rZJvESSLPMZanKVTTBa22eBGlZCJmpFqL0mWJcJaa+esuDYXkopXJBeGyKtDyzCX+0O6PFWJF/inJeZpUyxJoCSxY1NUcOSZyKh/0s0jpxwMHkFlCgJvs4LzVllKR8FfisutabdLbZTtHq+jmXj99fCsSLHWgTOaDYstJySciVr4rpw1TbQ6EAuZGnxLIDLq7bfSVWpzwJ4fvW03kh45Vz9gKYHPfrAz5x3ev7WCa4G7WeCmK8TU4YJiATzQlmUceUid6MXDpudZ8/OTonF53ZC+O8GooAy/bEcrc3AoPVidCVLBZwCc1L63O9TnlSrViR7cYwFZRZvY6ZLJUQTBrcWZYIJ6bpTRQwal1fPkjMXi3Pl1u16uaLVT/UiocXF0/TMoxlbLhOuE3itCNPF09TbymU79z+u2rX1dFK35x8jJ1SlrG+/ogs99s5FjeBidZkQdK8otLoVPk6ZLnQq+DNcXj0jTZsAOrmiddstfVIopUEbONkUWrkEmHg/gMnkncvBAk0L3vNbkZc5mePfOm2okGsDjcvOM7KudtucsqOALYURM5EJWwdsh5h12dvBL9OP4Th8Eb4LJ79MP1yPh4N++CocvGTBgfreYvVxgwUSYayQi1KYlPywnGUihkbsTc3wOZ6RZdVVTF0sN6iqRN2k2sAftyI59I86YMq8HBIxnyP5K0XzuViUms8ykgrOxa3zuaUwJc9qGuK67n1BwZUYN2BSyqkkSsPzuqQ+35bQYCpjMYd//v0fsBWMKxJmqrRkm8qUVJvwOVqfkqAJ35dVFyaud0jInseD/mgwYQFDWeas+/lhGR8cbh4+2B9+ePEu7LMvh6rdDQh7Cvq9cmBbXI980GD393UEERoT1rW6xIDdNpUWCyF5NuSa59euLmAzqsIdtO9vXFC4aLf/g8rc9yZTXojpVzxRVYS+d3EUg8ZCo0FJiWlTOYBHAY0F5VLSxhnlWJeyW5EcUe3qrIxsQxX8W4mw7NTxZV2gGqsoN9f9G9VHVNy7nHRcyL7fK2Tj2gSWgoOHnhCsK1H2C92Gq3LdTWcnCtuHehR/yZSSEJ1vEnDCLTbd7gnnd7H2Rx967IYeu6H/n27oK1bfc7mMGzstDSY/6ECPDdZjg/XYYP2vNVhL5UP6dI+FQ45Ow1FhvxQJUjZDbJJyXYLEW1uPmbfPtSJ5QwnQoIUVpcodlBq5UZLkNRyFH8N3g9eD6adw8vPLUe/TdSuSb8Y3187d45TiehfmArMEVtyl4Ry1S6wH6KZERgteOdDaQDuXkRQGSukRJWCUU4dfEgErobEZq7zgVlCRTmzMhOS6ImatApSxSoRcnOxKjojYb05Gg483/d4kvLmejga98c31g/3JaINs5OWzkbaxuoxtSTFheyP4GyneGSqPXLwYverDs4vn7VYkPxhfB7qQ4ubnLhYazObNHSzzTK3MukM4JviEgrrgxtuuC+q6FL/2fSEP0e90Eb8njONzaiH6N++Ho5v34XhwEqT36lX4LvRb/Z9716+/g2r8YTgYjQcvv3N8gsuHW5VDXf3ROQOVS6U5bmnHk97kw/hAQrv92EmAnYNefxJ+HOzvEd9vDwEHfx2Go8HL3+3Mxp5SithF8uMl/GP//ti/H/XvdTvsHMFpaLcQuPHt0+bdpO9PfUz5kSy4Nynw7b4fFexbVw9M6Vq+eZlt3nu2iLSLdudH5gKncO83+NuLssrdsHGHPzx9iFWy74xC2suLraSEtLhA7S+zXGT7cYonifD18nAX7f1hbfgXj+4osD2gAJdFZ+W8J6tTATBHY/jiB3HqIl6HoxPCllBKvC0wJn9ArZXe1Seh5QtDfkE4RNzXmKC0gmeGzDtHmyp6h1soQ3cW3Kasy77zEpoFjFQz2r7cHdzyvMhwfxCy9ZbjqcRB5/t5DftlvwXb9FxbXCdbrbp830L5Anu7Xhexe2XMduy+BVznsy1F9Vx8C7Ib1R8KMzSOkXN1XGfe6HrA5Xv6VCzSZoHambGM/ThBxOT6tY4g55IvXAcG9Tv+FoQWUi6TrO4XyLF2H8nEHOMqzrDrPJC6MIr2gR9xVLS2KeZuIKNW7psGGVcBuGkHnZpUadvMDkcfrp7azNACt6TS56ub7jgfd6GbPregECAMmCITFoS0CuxKrTmglwORbMKTJ0cm+eSJyxK+ftt8ZGC6Lp5sGIOGs8oAtKL5S+DJwKCe6NSsYE18AG8+vR37AcfulKcmAbP52NNVX+5quprU3QKUMuGOmFOVUVO546db7faGIZkLauP1ftFqk1GQj+XcuUFt3C5aO2n5zyYOupRNeHz82OW/+LFLHZep4TovMi5c+Vtq98rMx8vPbEnZx3FCUW8vZn4JWErBtfuZ3d3RtPWDzu7vaftbibpi3c9fArbkWlDZRav7gPmJBet+vmNuvM76dR8/IVoIPCtdYjlMmvfB+gn/Ru5B2N34T+pggX9V0L1jucuwTPOVi7wUQN1nP84dCcDt3bGMy0XpMhrzOOnfvwBaMQVE
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Creates a new API key for a given actor. The secret is returned only once in the response and cannot be retrieved later. Keys can
-be scoped with specific permissions and have optional expiration.
+Creates a new API key for a given actor. The secret is returned only once
+in the response and cannot be retrieved later. Keys can be scoped with
+specific permissions and have optional expiration.
```http
-POST /v2/admin/issuedApiKeys
+POST /v2alpha1/admin/issuedApiKeys
{
"name": "production-service",
"actor_id": "user_123",
@@ -37,12 +51,31 @@ POST /v2/admin/issuedApiKeys
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
index 76d4d28b3c..3a777c3e7d 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
@@ -1,22 +1 @@
-{
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": { "format": "int32", "type": "integer" }
- },
- {
- "description": "Cursor token for pagination (OPTIONAL)",
- "in": "query",
- "name": "page_token",
- "schema": { "type": "string" }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination (OPTIONAL)","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
index a28a55dec5..14fa61109c 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
@@ -1,145 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "imported_api_keys": {
- "items": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- },
- "title": "List of imported keys",
- "type": "array"
- },
- "next_page_token": {
- "title": "Token for fetching the next page (empty if no more results)",
- "type": "string"
- }
- },
- "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
- "type": "object"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_keys":{"items":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"},"title":"List of imported keys","type":"array"},"next_page_token":{"title":"Token for fetching the next page (empty if no more results)","type":"string"}},"title":"ListImportedAPIKeysResponse returns paginated list of imported keys","type":"object"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
index de3457870e..d20394cbe0 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
@@ -5,38 +5,70 @@ description: "Lists all imported keys with filtering. Returns imported keys only
sidebar_label: "List Imported API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports pagination and AIP-160 filter
-expressions.
+Lists all imported keys with filtering. Returns imported keys only (not
+issued keys). Supports pagination and AIP-160 filter expressions.
```http
-GET /v2/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
+GET /v2alpha1/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
index 4a5e5fb847..e8f3ff5027 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
@@ -1,22 +1 @@
-{
- "parameters": [
- {
- "description": "Number of items per page (default: 50, max: 1000)",
- "in": "query",
- "name": "page_size",
- "schema": { "format": "int32", "type": "integer" }
- },
- {
- "description": "Cursor token for pagination",
- "in": "query",
- "name": "page_token",
- "schema": { "type": "string" }
- },
- {
- "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
- "in": "query",
- "name": "filter",
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
index e9fcb6db7c..c96bcede2f 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
@@ -1 +1 @@
-{ "title": "Body" }
+{"title":"Body"}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
index e0da39abf9..4560c5eee2 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
@@ -1,138 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_keys": {
- "items": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": {
- "format": "date-time",
- "type": "string"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": {
- "items": { "type": "string" },
- "type": "array"
- },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "type": "array"
- },
- "next_page_token": { "type": "string" }
- },
- "type": "object",
- "title": "v2ListIssuedAPIKeysResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_keys":{"items":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"type":"array"},"next_page_token":{"type":"string"}},"type":"object","title":"v2alpha1ListIssuedAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
index 63fa1c0539..6295f1f64f 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
@@ -5,38 +5,71 @@ description: "Lists issued API keys with optional filtering. Supports cursor-bas
sidebar_label: "List Issued API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter expressions. Returns only
-issued (generated) API keys; use ListImportedAPIKeys for imported keys.
+Lists issued API keys with optional filtering. Supports cursor-based
+pagination and AIP-160 filter expressions. Returns only issued
+(generated) API keys; use ListImportedAPIKeys for imported keys.
```http
-GET /v2/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
+GET /v2alpha1/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
index b19b7ceb16..02cd67dfcd 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
@@ -1,10 +1 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"Identifier of the key to revoke, taken from the path\n(`POST /v2alpha1/admin/apiKeys/{key_id}:revoke`). For issued keys this is\nthe UUID; for imported keys this is the SHA-512/256 hash. REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
index fe11762f69..61224ec4e1 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
@@ -1,34 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "description": {
- "description": "Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.",
- "type": "string"
- },
- "reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- }
- },
- "type": "object",
- "title": "StaticCredentialsAdminRevokeAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"description":{"description":"Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"}},"type":"object","title":"StaticCredentialsAdminRevokeAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
index d3cec6dad6..f7e1bfaac2 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
@@ -1,36 +1 @@
-{
- "responses": {
- "200": {
- "content": { "application/json": { "schema": { "type": "object" } } },
- "description": "A successful response."
- },
- "204": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key revoked successfully."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"API key revoked successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
index 9ebbf602ee..c0325d307d 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
@@ -5,41 +5,74 @@ description: "Immediately revokes an API key (issued or imported). Once revoked,
sidebar_label: "Revoke API Key"
hide_title: true
hide_table_of_contents: true
-api: eJydVttu20YQ/ZXBPiUGJbtqC6R8quLICePEkiUlzoWBs+KOxI2Xu+zuUDZhEOhH9Av7JcUuGVmRFATpA0EuOZwzlzOXeybQZVaWJI1mMUuKAoXkhKoGi2tzgw64huEkgRus4ZF0rkIBxoIsSmMJxeM+jHWGnbSIgHL0sqnOuAZtQBm9QgsLhMqhgKWxwCvKUZPMuIftwzyXDkyJNpxBOpDW4hqtkwuF/VRPW+VerwNuPRpxqTfqhCQoK1sah66f6lR//vw5JypTPRnP5nC8HhxzUUh9zEt5jrU7PvnlxeWHd3+8fX95/vLpk3eXHy7b691l3DqS6vtUA6TMIndGpyyGlE1Hb8enw3kyvriejoaz8cX1+ej99en49WQ6fp3MRilLdRPAWcQ2/iSCxWzo4Vs3hpPkHGsWsZJbXiChdSz+eM+kT0DJKWcR07xAFrMbrK+lYBGz+FclLQoWk60wYi7LseAsvmdUl17SkZV6xZrmUyuMjp4aUXuJzGhCTf6Rl6Xqon78xfmM32+pKq23mSQ6f/qGGDtHNg4PXMHSIvYI7wjwrlRcdxkda1UDV8rcooDbHDW0cfS5nUyTt8mr0fPR9VUyf/FsOry66LNo15Goi3yLveSVIhYfyMCbi9lkdJqcJaNnLNqx0se79XbaopfWrKVAB45slVFlUQTitkKdjQ6kdqWPNixqmJ6dwu+DJyf9VL/x/JUaFoZyCHwCrgU4VMvelpalMrctC6EH+wYfcD+GQI+e0aqOQRvahE7qXfUsYqirgsUffxiMH9H1oMjw7Cx5lbSvTl8ML55/R9XszWQ0nY2efefzAS/Zp90kR4wkKf9iPdjNFWuajbhZfMGMtsRnxElmpxaFbyNcub3yCuRvmma/dO56xsqV1FxNfP1dtJW2CPJe2pVGu7YEBicnP1VA35ob0L8l5BBclWXo3LJS8BWq73EHJ7/9DNQh3V2P7hrxFpKqA8Smiv53S8iMQH9fGltwX45S06+Dh9qVmnCFtgUjLlX4SxIW4YELIdu2MdlW20Q7MH+26vZ72/cJUVpDZlEthzpksRPj1vJwLtA5vvpJnbbMPM8qdzCTGiqNdyVmhALQWmO3E+rV8pXv6/tc9XVQIOXGz4XSOAqjgHIWs/1Bdd+OgKYbSyxiPknThw4/uuNFqXC/RW9q7Gsf/UG/aCIm9dIc6PW2hjlXxvnmzSGXq7xXog0k8JPfBQch23gIBdd8hQVqAod2LTPsQ0KQcy0UurAheFpu/6LkErM6UxiD3zGkXoVhH8EarVzW/kw5FsAJlLkFxQl1Vkcg0Mq1/+pyY6mn5BoFkLlB7eDRy6t56NCvecatMfpxFI4hlP4fHioktOp5jmHLkQ5cqSSB1GSAbs1XD1zsxXpwdLSX0KMj+Pfvf7qJsBn7Lg7luHGsW54isIY4+XvIaNRtUp0r2Bkfwcur89njYG8IQVejnQmolrPWrg48TInO1O2R5vejrTDnRgm/bzyw/CG7w0nCIha2rpD3Qf+ENc1/EaGFAA==
+api: eJydVtty2zYQ/ZUdPMUeSnbcppOyL1VsOWacWLIkx7kwY0PkUkQMAiywlM3xaKYf0S/sl3QA0rIsKU3TB40IcrHXc3b3nqVoEyNKElqxkEVFganghLIGg3N9gxa4gt4wghus4ZmwtsIUtAFRlNoQpjtdGKgEW+k0AMrRycYq4QqUBqnVDA1MESqLKWTaAK8oR0Ui4c5sFya5sKBLNP4MwoIwBudorJhK7MZq1Ch3ei1w46wRF2qpLhUEZWVKbdF2YxWr6+vrnKiM1XAwnsDe/IDLMufP93haCLXHS3GKtd3bf35y/unDr+8/np++efXyw/mn8+b34TxswonVfawAYmaQW61iFkLMRv33g8PeJBqcXY36vfHg7Oq0//HqcPBuOBq8i8b9mMVq4V1gAVtGFaUsZD1nvgmmN4xOsWYBK7nhBRIay8LP9+v1SF2eMoEGdPaQWiDdpjsA4jeoIDO68F9LTnmsnl3/a9j3N1hfiXTRBnm904VjV9Gmtj7H5CoibKyc0ouL6Og3n+mHoj8R8obHJ73Oi+cHewcvfoGc27wLo/75RTTqH3VZwISLxfnGAqZ4gSxkjQ8sYAb/qITBlIVkKgyYTXIsOAvvGdWlk7RkhJqxxeJLI4yWXum0dhKJVoSK3CMvS9kCau+rdcm7X1FVGlcIEmjd6UmO11M+8A9cQmYQO4R3BHhXSq5asA6UrIFLqW8xhdscFTTgcJkYjqL30dv+6/7VZTQ5ORr1Ls9c+GuBBC2cGtsZrySxcAusLs7Gw/5hdBz1j1iw5qUDURPtqLFeGj0XKVqwZKqEKoOpB0kj1PpoQShbumzDtIbR8SG8OHi5343VhaOmUDDVlINHC3CVgkWZdVa0ZFLfNgSDDmw6vCX8EDzmO1rJOgSlaZk6odbVs4ChqgoWfv5uMr7Hwa0ivePj6G3UvDo86Z29/oaq8cWwPxr3j77xeUuU7Mt6kQNGgqR78UDC9YqxxWJ5SU+/YkIrl8bESSSHBj3/ubQbncNTYLFYbBLorqONmAnF5dC1lrOGb1Mv76RtqZVtiHCwv/9DNHrqrrf+FJY9sFWSoLVZJeHBVNfZPdj/+UdMbdPdDqF20qxYkrU3seTS/24MiU7R/WfaFNyRUij66eCRwUIRztA0xogL6W8JwsI/8DQVTfMYrqpdBGtmfm/UbXa4bwOiNJr0tMp6ylexFePGcH8u0Fo++0Gdpkwcziq7tZIKKoV3JSau36Mx2qwW1KnlMzeyNrHq2FAg5dqNvFJb8lOOchay/ziSWMBcqUaP3b5/x4tS4ma7XvLtoad+p3cs3DTK9Ja+b2qYcKn9SOOQi1neKdF4KLgFx/owIVnGCQVXfIYFKgKLZi4S7EJEkHOVSmzGogPn6hUpMkzqRGLox61QMz9KA5ijEVntzpRjAZxA6luQnFAldQApGjF3X22uDXWkmGMKpG9QWXj25nLiu/U7nnCjtdoJ/NGn0t3hnie+bU9y9MucsGBLKQiEIg10qx8isKET68Du7kZZd3fh7z//aqfDcq+xoSflMrB2RwzAaOLk/ttNpdkd2lCwdT6AN5en4x3vr09By9TWBZTZuPGrNe4nRuvq6nhzy8lKmnMtU7dQPWL9sbq9YcQC5pdLX/cHRLLF4h/QvNbf
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for authentication. This
-operation is irreversible. Revoked keys are retained for audit purposes.
+Immediately revokes an API key (issued or imported). Once revoked, the key
+can no longer be used for authentication. This operation is irreversible.
+Revoked keys are retained for audit purposes.
```http
-POST /v2/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
+POST /v2alpha1/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
{
"reason": "REVOCATION_REASON_KEY_COMPROMISE"
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
index f832c1b781..05941f5ce6 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
@@ -1,11 +1 @@
-{
- "parameters": [
- {
- "description": "key_id is the ID of the existing API key to rotate",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"key_id is the ID of the existing API key to rotate","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
index a6617b6abd..6cc8628ec3 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
@@ -1,77 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": {
- "title": "metadata for the new API key (inherits from old key if not provided)",
- "type": "object"
- },
- "name": {
- "title": "name for the new API key (inherits from old key if not provided)",
- "type": "string"
- },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "scopes": {
- "items": { "type": "string" },
- "title": "scopes for the new API key (inherits from old key if not provided)",
- "type": "array"
- },
- "update_mask": {
- "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
- "type": "string"
- },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "StaticCredentialsAdminRotateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"metadata for the new API key (inherits from old key if not provided)","type":"object"},"name":{"title":"name for the new API key (inherits from old key if not provided)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"title":"scopes for the new API key (inherits from old key if not provided)","type":"array"},"update_mask":{"title":"update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"StaticCredentialsAdminRotateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
index 8c6dc535d3..fd0c89e7b6 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
@@ -1,223 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "old_issued_api_key": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- },
- "secret": {
- "title": "secret is the new API key secret (only returned once, never retrievable again)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RotateIssuedAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "201": {
- "content": { "application/json": { "schema": {} } },
- "description": "API key rotated successfully. New key issued, old key revoked."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"old_issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"secret":{"title":"secret is the new API key secret (only returned once, never retrievable again)","type":"string"}},"type":"object","title":"v2alpha1RotateIssuedAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key rotated successfully. New key issued, old key revoked."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
index f7679ff402..9899c3ba2d 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
@@ -5,48 +5,80 @@ description: "Generates a new secret for an issued API key. Creates a new API ke
sidebar_label: "Rotate Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
-
+
+
-
+
+
+
-Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret, and immediately revokes the old
-key. This is the recommended way to update scopes, metadata, or rotate credentials.
-For zero-downtime rotation, use this workflow instead:
-1. IssueAPIKey with new credentials
-2. Deploy new secret to all services
-3. Verify new secret works everywhere
-4. RevokeAPIKey to remove the old key
+Generates a new secret for an issued API key. Creates a new API key with a
+new key_id and secret, and immediately revokes the old key. This is the
+recommended way to update scopes, metadata, or rotate credentials.
+
+For zero-downtime rotation, use this workflow instead:
+ 1. IssueAPIKey with new credentials
+ 2. Deploy new secret to all services
+ 3. Verify new secret works everywhere
+ 4. RevokeAPIKey to remove the old key
```http
-POST /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
+POST /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
{
"scopes": ["read"]
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
index 5881cc93c2..84eb488ec3 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
@@ -1,11 +1 @@
-{
- "parameters": [
- {
- "description": "SHA512/256 hash of the imported key (REQUIRED, path param)",
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED, path param)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
index 432ca719c3..50adb4b243 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
@@ -1,56 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "update_mask": {
- "title": "AIP-134 partial update mask",
- "type": "string"
- }
- },
- "type": "object",
- "title": "StaticCredentialsAdminUpdateImportedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"title":"AIP-134 partial update mask","type":"string"}},"type":"object","title":"StaticCredentialsAdminUpdateImportedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
index b6035db77e..7c2e8fbd5b 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
@@ -1,125 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": {
- "title": "SHA-512/256 hash of credential",
- "type": "string"
- },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2ImportedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.api.mdx b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
index 87ba190cee..c5de14cab0 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
@@ -5,41 +5,74 @@ description: "Updates metadata, scopes, or rate limits of an imported key. Suppo
sidebar_label: "Update Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "patch api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Updates metadata, scopes, or rate limits of an imported key. Supports partial updates via update_mask (AIP-134).
+Updates metadata, scopes, or rate limits of an imported key. Supports
+partial updates via update_mask (AIP-134).
```http
-PATCH /v2/admin/importedApiKeys/{key_id}
+PATCH /v2alpha1/admin/importedApiKeys/{key_id}
{
"name": "New name",
"update_mask": "name"
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
index b19b7ceb16..f561110464 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
@@ -1,10 +1 @@
-{
- "parameters": [
- {
- "in": "path",
- "name": "key_id",
- "required": true,
- "schema": { "type": "string" }
- }
- ]
-}
+{"parameters":[{"description":"UUID of the issued key to update, taken from the path\n(`PATCH /v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
index 00ba7a70c8..1fa9ea943c 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
@@ -1,53 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "update_mask": { "type": "string" }
- },
- "type": "object",
- "title": "StaticCredentialsAdminUpdateIssuedAPIKeyBody"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"type":"string"}},"type":"object","title":"StaticCredentialsAdminUpdateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
index f922dc595f..fa372beabf 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
@@ -1,122 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
- "properties": {
- "actor_id": { "type": "string" },
- "create_time": { "format": "date-time", "type": "string" },
- "expire_time": { "format": "date-time", "type": "string" },
- "ip_restriction": {
- "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
- "properties": {
- "allowed_cidrs": {
- "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
- "items": { "type": "string" },
- "type": "array"
- }
- },
- "type": "object",
- "title": "v2IPRestriction"
- },
- "key_id": { "type": "string" },
- "last_used_time": { "format": "date-time", "type": "string" },
- "metadata": { "type": "object" },
- "name": { "type": "string" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "revocation_description": {
- "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
- "type": "string"
- },
- "revocation_reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "status": {
- "default": "KEY_STATUS_UNSPECIFIED",
- "enum": [
- "KEY_STATUS_UNSPECIFIED",
- "KEY_STATUS_ACTIVE",
- "KEY_STATUS_REVOKED",
- "KEY_STATUS_EXPIRED"
- ],
- "type": "string",
- "title": "v2KeyStatus"
- },
- "update_time": { "format": "date-time", "type": "string" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2IssuedAPIKey"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
index c500f6645d..f046df1542 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
@@ -5,42 +5,74 @@ description: "Updates metadata, scopes, or rate limits of an issued key without
sidebar_label: "Update Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: eJztWu9u2zgSf5UBPyWF7CTtXtHzfjnXcVs13cS1nba7VeHS0sjiRiJVkrIjBAHuIe4J70kOQ8r/nd10vxxw1xZNY2o0nBnOn98MfccSNLEWpRVKsg67LhNu0UCBlifc8gBMrEo0ASgNmluEXBTCGlApcAnCmAoTuMEaFsJmqrKgleVWyFkkbYZgMNZo23BtEIb0BEP3SncQXmANVkGccTlD2CCOZCS/fv2aWVtGctAd997Ayfwpz8uMn53wpBDyxO/bLcUF1ubk9OzN+98+/f3Dr+8v3r588en9b+/9v0/vI3kXSYCIeS0i1oHPEdPIk4h9Cfyjyqk8Kbi5oedr2kjeO0FYwFSJmpOJwoR1WJdk8Jba1IYFrOSaF2hRG9b5fLdr2+vwnOxGqm4YzirwIgRg+Q1KSLUqHFHJbRbJo6+PscHdDdYTkdx/PW7DsP/+Ohz2z9ssYIJ2JkYsYJIXyDrMU7KAafxWCY0J61hdYcBMnGHBWeeO2bokSmO1kDN2f//FE6OxL1VSE0WspEVp6VdelrmInXlOfjek6t0Gq1KT8axAQ59EOdFIbGNvlF0bhYPh+jEkmAqJBsJBa8oNJsDjGI0B2lyr3ECqNLlhdxCSKduR/JihBJ7naoHJJBaJNiAMSCVbWJS2DkDJvIZGF+NNHQ4MFNzGmZAz4BZy5MaCkhjJXng+BO0clGuEEnUhrMWkDX1it7NTgVzSZhAOYENLOOJ57nZpyI/bkdwmMUBGdL6glbJLhYDLBERRKm0bZ5mjFmljbKfLz5FMUIs5JmDVDUoDR28/jk8KHnOtlDx2chsKvJwsRwylsmCq6e8YW9owHECcYXxjyF22T2tLvf3D2rMzh1yQ6VJYG86Azbh1YjT0zuMNhbwwzbGNqpKUNDBVNoNwMP8JjrA9awcQsbPTtvt78iJix06BcDB/vn7+9PT0rJNMX3Q6J8+eRswZN4XmuFeW39j+SKpN2x+7MLFYmAOeHywXuNa8ZvfrBeUMyAJmhc1pYRmeWy5MHJa5dIN98/L9MiYP7EvJduKS7aRUuYjrffsPucV3RDFwBOCfTp3JcSNbg2ewHy2RDCVcjUZQqITSDx1IQysMCJkqXThX47kzPDm485kpUgyaqsAEpnUkq9JYjbyAGbe44LWBo76cqzqAXq6qJM25xgDQxu1jJwUS6xgLlJTuQwmxKgrUseB5I8uY58os6cxW6akMBaqQrQILpWuqTENMhIEpj29QJiaIpPOjUi1QOwmdQV73hl04eo0StYihh3kOZEHo5jOlhc2KY2eSnirKXJCiVNIg0Ty1LYE2bVFF4qVokTBOllaGPEFtWmen+8HzrVL+zLcPzS2TeUkkWRVT1BQwq5S09NISNSyETNSCWPuTYB0mpH3+Ewv2/aWSwmXjpTvS5x2P8Fu7B/R6O5LnmPIqt1T1lgJQ3buyGWqY81wk9LNC48QJ++NXYEqMib4pAK1pbalYBn4prrSm1TW3Q7J6vfZt49eXxrGiwMYEzmlWKrTdIRVKNsJ14PmpgaMzKISsLB4H8Oz5qV/JVKWPA3jx/KdmIeG1C/jdCvfncb0TbaSHRwqurj0yfwSbcONQpX1YjhHhqrinMUFpBc/NAzDEVeh74rRb329bSouZkDwfEE659HBg6uiJ2pRKGq/P09PT76ryO1V8E+NpLDUalOTbq+SzBEBHMwpHbjE5pjB1Ud+O5JCK4A3WPnGrkn+rEOZn4MNgWemMVRTeQjrXoBRLKMG59X5F/GWrIsYaaVOYCw6eeky0LsttV8wjVy7dTscHKmRslSY0dejo/SYT8mN6vophOrGWWz0QG3hbCv29L/2AVT9g1f8brGramD3zjVDPUbdWiQVc3yVc1kwF6lUtWfdgrj9NgJuNtmvVyoGSgHPUNbi+C1AmpRKEg+gAfGeIhqiWlqee7fHd2sjyaY4rqXKRoqt8KvUt9A3WPzddtZJQapVUhIg4SFyA53OgoAUs58ZOKoPJd+aSH3D1B1z9AVf/F+GqxrnyNW6ypciuXofpKPXMRYJU3hFbdMQOMeCt9aEK6/fakbwiRGDQwoKwwwZLjdwoGh3CYBh+CN/1X/cnH8Pxm/Nh9+NlO5JvR1eXLuj9ZLADqcA8gQV3uKRA7ZDGDrsJidGGV460cdOzZ5EUBirpGSVglDuUZuIoDCyExlasipJbsczBUyG5rklZqwBlrBIhZwcT7J4Q3pLORSnd9T9c9brj8OpyMux3R1eXk+vL0aDfC1+F/XMW7CbHFbOht8/K2sbqKrYVZYb1juB3pKxnCC+6rDF81YO/PX1x2o6kq2dC+sLv6xZlRIN52trgkuZqYVwagRbsC3zggDrg2o4WgaSOwzzLDCDkLnsWMJRVwTqf/9QY+88v+r9Oele/DIZXv4Sj/kGS7qtX4bvQL/XedC9fP8BqdD3oD0f98wceH9CSfdk97wMBtnNif7UhJBRZmW3fIeVH4+74erRjp6U9HyTYeNDtjcMP/e010v5il7D/aUDj4scofYH1yMu7bmW/D17MhRFTkQtb76v8IRyFL8N34fjXP4yVC6w/rLhAIgzdN1TCZJT4q2kuYjiKc0GJ3fAUj30n6ZoSf8UAR8aDRPJi/7gdyYF/1RETkOaQiDRFKhCU6FIxq7SDaqXGVNy6bDEXpuJ5I0PcpL6XFHSkuAGTEUR2lxu8QH+ZcuL6HWMoAE1tLBbw73/+C9aGcZh/SpcpeFsqU1GrwVO09TJSH7ZVB8ZNZ8sNjPq9YX+84zUP2njn4erlnfXB9ct3Ye+RvrI+psdh/M3bFDfC2D74LpjKtapplcNyXtFmjq7xo798MxGrZNuLhbTPnq49WEiLM9R+M8tFvh3mPEmEh56DTbb3uzDrH57d9wx+XCmaVmlX1ofyR4HG8Nl38tRlvIzjA2aWUEm8LTEmR0Kt6e5vbW1iy2d0w7U/kyK/KNBmKvHXTnHmbsVsxjrscS0RCxgd1XB93dS/5UWZ4+Hro51e+vNS+S/bncyqdVm768GOpUHBayqPU9efl1hwI6Mtk/56750p3+agRqZqH3Bd6Wb05bv9TMyyVonauaKM/aBBxDS0auwMBZd85hoSoFQmYmxDaCHjMskb+JxWeb75CjWWcR3n2HGdLzUllOoCP/yo6bPNsHCjGrWAnFuUcR2Am4PQU5MpbVv57lDEAYvVdC1wHwkD3Li5jwtXl7fGGTpYJwyYMhcWhLQK7EItNTAdImvBkyd7bvXkiUuRHsisLmNNxw1vVorBkXOpwHfL9D+JgUEz62lUwUb4AN5+vBj50cfm/KcRAfN05OVqNnfgphF1E4lRGdgwc6Zy6rE2Ym19ut1ByAI2R238uS8DgjyjVMYW3Pl046l+tAs+KTrT+UvmHey+ync/Lu8PX943OZA6hJMy58IhtUrnrga41PR5fRIBc0LS7GpTTBawTjNw+hKwTBlLb93d0fz0Wuf397T8rUJds87nLwGbcy0IK/ivAQhDvyesk/Lc4B+c4NGwGdkfw3/l2wIHTbUsOJKcz7WwrEN98g3W628T3FPC9fMFp7N/2Gu67jGxWL+8V5fvg+Ub3TjG0v4h7WaJccqywF9idO5Y4ao403zhMvzCS6qcqV39dWt3LOdyVrmqyTxT+vMfVSM2iQ==
sidebar_class_name: "patch api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedAPIKey to change the
-secret.
+Updates metadata, scopes, or rate limits of an issued key without rotating
+the secret. Use RotateIssuedAPIKey to change the secret.
```http
-PATCH /v2/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
+PATCH /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
{
"scopes": ["read"],
"update_mask": "scopes"
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
index b4df248475..ddf5c2ce0a 100644
--- a/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
@@ -1,21 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "credential": {
- "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyRequest"
- }
- }
- },
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2alpha1VerifyAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
index 15e5a9ea5b..d0082d7018 100644
--- a/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
@@ -1,113 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "actor_id": { "type": "string" },
- "error_code": {
- "default": "VERIFICATION_ERROR_UNSPECIFIED",
- "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
- "enum": [
- "VERIFICATION_ERROR_UNSPECIFIED",
- "VERIFICATION_ERROR_INVALID_FORMAT",
- "VERIFICATION_ERROR_EXPIRED",
- "VERIFICATION_ERROR_REVOKED",
- "VERIFICATION_ERROR_NOT_FOUND",
- "VERIFICATION_ERROR_SIGNATURE_INVALID",
- "VERIFICATION_ERROR_INTERNAL",
- "VERIFICATION_ERROR_IP_NOT_ALLOWED",
- "VERIFICATION_ERROR_RATE_LIMITED"
- ],
- "title": "VerificationErrorCode provides type-safe error codes for verification failures",
- "type": "string"
- },
- "error_message": {
- "title": "Human-readable error message (only set if is_active=false)",
- "type": "string"
- },
- "expire_time": { "format": "date-time", "type": "string" },
- "is_active": { "type": "boolean" },
- "issuer": {
- "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
- "type": "string"
- },
- "key_id": { "type": "string" },
- "metadata": { "type": "object" },
- "rate_limit_policy": {
- "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
- "properties": {
- "quota": {
- "description": "quota is the number of requests allowed per window.",
- "format": "int64",
- "type": "string"
- },
- "unit": {
- "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
- "type": "string"
- },
- "window": {
- "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
- "type": "string"
- }
- },
- "type": "object",
- "title": "v2RateLimitPolicy"
- },
- "rate_limit_remaining": {
- "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
- "format": "int64",
- "type": "string"
- },
- "rate_limit_reset_time": {
- "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
- "format": "date-time",
- "type": "string"
- },
- "scopes": { "items": { "type": "string" }, "type": "array" },
- "visibility": {
- "default": "KEY_VISIBILITY_UNSPECIFIED",
- "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
- "enum": [
- "KEY_VISIBILITY_UNSPECIFIED",
- "KEY_VISIBILITY_SECRET",
- "KEY_VISIBILITY_PUBLIC"
- ],
- "type": "string",
- "title": "v2KeyVisibility"
- }
- },
- "type": "object",
- "title": "v2VerifyAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"type":"string"},"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"issuer":{"description":"The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.","type":"string"},"key_id":{"type":"string"},"metadata":{"type":"object"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1VerifyAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/admin-verify-api-key.api.mdx b/docs/talos/reference/api/admin-verify-api-key.api.mdx
index 7cdaf0e35a..d832dc4c91 100644
--- a/docs/talos/reference/api/admin-verify-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-verify-api-key.api.mdx
@@ -5,48 +5,80 @@ description: "Verifies a single API key or derived token. Validates the credenti
sidebar_label: "Verify API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
-
+
+
-
+
+
+
-Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with
-any credential type (issued keys, imported keys, JWT, macaroon). The verification result includes decoded claims and metadata —
-admin access only.
-Cache Control (HTTP Headers):
-- Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
-- Cache-Control: no-store - Bypasses cache read AND write (never cached)
-- Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
+Verifies a single API key or derived token. Validates the credential's
+signature, expiration, and revocation status. Works with any credential
+type (issued keys, imported keys, JWT, macaroon). The verification result
+includes decoded claims and metadata — admin access only.
+
+Cache Control (HTTP Headers):
+ - Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
+ - Cache-Control: no-store - Bypasses cache read AND write (never cached)
+ - Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
```http
-POST /v2/admin/apiKeys:verify
+POST /v2alpha1/admin/apiKeys:verify
{
"credential": "sk_live_abc123..."
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/batch-verify-api-keys.api.mdx b/docs/talos/reference/api/batch-verify-api-keys.api.mdx
deleted file mode 100644
index b5aacf33b1..0000000000
--- a/docs/talos/reference/api/batch-verify-api-keys.api.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
----
-id: batch-verify-api-keys
-title: "Batch Verify API Keys"
-description: "Verifies multiple credentials in a single request. Efficiently verifies up"
-sidebar_label: "Batch Verify API Keys"
-hide_title: true
-hide_table_of_contents: true
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
-verified independently; partial failures are returned in the response.
-
-```http
-POST /v2/apiKeys:batchVerify
-{
- "requests": [
- {"credential": "sk_live_abc123..."},
- {"credential": "sk_live_xyz789..."}
- ]
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
index d29e1bf998..dadc4eb06f 100644
--- a/docs/talos/reference/api/ory-talos-api.info.mdx
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -1,36 +1,46 @@
---
id: ory-talos-api
title: "Ory Talos API"
-description:
- "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
- verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
+description: "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
sidebar_label: "Ory Talos API"
hide_title: true
custom_edit_url: null
---
-import ApiLogo from "@theme/ApiLogo"
-import Heading from "@theme/Heading"
-import SchemaTabs from "@theme/SchemaTabs"
-import TabItem from "@theme/TabItem"
-import Export from "@theme/ApiExplorer/Export"
+import ApiLogo from "@theme/ApiLogo";
+import Heading from "@theme/Heading";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import Export from "@theme/ApiExplorer/Export";
-
+
+
-
+
+
-Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
-verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
+
+
+Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
The API is split into two services:
- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification
-- **SelfService** — self-service verification, batch verification, and revocation for credential holders
+- **SelfService** — self-service revocation for credential holders
+
+
### Quick Links
- [**Admin Plane**](./admin-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
-- [**Data Plane**](./verify-api-key) — High-performance verification (single, batch, self-revoke)
+- [**Data Plane**](./admin-verify-api-key) — High-performance verification (single, batch, self-revoke)
```mdx-code-block
import DocCardList from '@theme/DocCardList';
diff --git a/docs/talos/reference/api/revoke-api-key.RequestSchema.json b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
index 5f67130aa1..7d776c606e 100644
--- a/docs/talos/reference/api/revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
@@ -1,36 +1 @@
-{
- "title": "Body",
- "body": {
- "content": {
- "application/json": {
- "schema": {
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "properties": {
- "credential": {
- "title": "Full API key secret or imported key (REQUIRED)",
- "type": "string"
- },
- "reason": {
- "default": "REVOCATION_REASON_UNSPECIFIED",
- "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
- "enum": [
- "REVOCATION_REASON_UNSPECIFIED",
- "REVOCATION_REASON_KEY_COMPROMISE",
- "REVOCATION_REASON_AFFILIATION_CHANGED",
- "REVOCATION_REASON_SUPERSEDED",
- "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
- ],
- "type": "string",
- "title": "v2RevocationReason"
- }
- },
- "type": "object",
- "title": "v2SelfRevokeAPIKeyRequest"
- }
- }
- },
- "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
- "required": true,
- "x-originalParamName": "body"
- }
-}
+{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","properties":{"credential":{"title":"Full API key secret or imported key (REQUIRED)","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"}},"type":"object","title":"v2alpha1SelfRevokeAPIKeyRequest"}}},"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/revoke-api-key.StatusCodes.json b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
index 506ca96823..b870249cb8 100644
--- a/docs/talos/reference/api/revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
@@ -1,40 +1 @@
-{
- "responses": {
- "200": {
- "content": {
- "application/json": {
- "schema": {
- "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
- "type": "object",
- "title": "v2SelfRevokeAPIKeyResponse"
- }
- }
- },
- "description": "A successful response."
- },
- "default": {
- "content": {
- "application/json": {
- "schema": {
- "properties": {
- "code": { "format": "int32", "type": "integer" },
- "details": {
- "items": {
- "additionalProperties": {},
- "properties": { "@type": { "type": "string" } },
- "type": "object",
- "title": "protobufAny"
- },
- "type": "array"
- },
- "message": { "type": "string" }
- },
- "type": "object",
- "title": "rpcStatus"
- }
- }
- },
- "description": "An unexpected error response."
- }
- }
-}
+{"responses":{"200":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success","type":"object","title":"v2alpha1SelfRevokeAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
diff --git a/docs/talos/reference/api/revoke-api-key.api.mdx b/docs/talos/reference/api/revoke-api-key.api.mdx
index 69dee11285..742ea686ea 100644
--- a/docs/talos/reference/api/revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/revoke-api-key.api.mdx
@@ -5,44 +5,79 @@ description: "Allows an API key holder to revoke their own key. The caller must
sidebar_label: "Revoke API Key"
hide_title: true
hide_table_of_contents: true
-api: eJztV9tu4zYQ/ZXBPCWB7KRZFCj0VDdxdrXZTVw72aCIgiwtjS1uKFIlKSeCYaAf0S/slxQk5Uu83g0C9KEo6hdL5HA4lzNnRnPMyWSaV5YriTH2hFCPBpiE3iCBB2qgUCInDVaBppl6ILAFcQ3qUbrtLlwVBBkTgjSUtbFQaTXjOaXSFgSTWoiVJkOZJgvMOBk1ATWBShlDxnAluzCqq0ppa4AbU1O+PGZSyWQOvHSblPulLry/uQK3XLKMaaUkWPVA0kDGpFQWxgSGxKQTTM5hzxbUpJJpAmOZJUHG7HdTmUpn/mCYfEo+9N/272+Sq3enw97NBWhiRkngBpw+5sJCOUyUXivOmAtaKvdYXnLZUVI0Qefnz58La6tUDi5HV3A4Oz5kFT+nxsTu7NDblMp5KgFSzDTlJC1nIsUYUjQP94LP6J6Nsx+O33S73RSjIBlMClLD/qfLk95VcnlxP+z3RpcX9+f93+5PLj8Ohpcfk1E/xVQuvCUYoapIe1uTHGMM9/cGyTk1GKGm32sy9heVNxjPMVPSkrTukVWV4MHJwy/GwWOOJiuoZO7pOW5GK8eC4mHQGgL3Cjylcty0EOJyCisMvYwfjLDSzlPLyXhPVoF1b5ZbQRjj2Q5EKv0MXrA37P96nQz7p/sYoW0qd85YzeUUF1GbhhCCCauFdTH9Kh3XF6NB/yQ5S/qnGG0Fa7gCzzCgrK0ZA8bqOrO1phzWCGuxaIBLU3G3N25geHYCPx7/dNRN5bWhHLiEsbIFeCz60tjCKUxcJjw+oQNfG7yjCGLorZAdP6sDLrfVY4Qk6xLj2xeD8RJ2d4r0zs6SD0lYOnnXu3j7DVWj60F/OOqffmN7h5d4t53kaIWW2fF2rnCxWImr8RfK7DPxb9QBLtyxf2HJuOp3kMLY6poifOoozadcMjFgmpUXrHR+jR05eOibSkkT6uv46OgfJYyg2jGuJltrSTkoCabOMjJmUottxHko98vKNhty+LrkhDt3Zae3efPS7y56ubbqX+H7FjOpnNz/ROmSOfrg0r45XpvOpaUp6XCZZVz4U9xS6R9YnnN3DxODTbWLbQL8Oaibb1PYdwBcaWXVuJ70pM93K8a0Zv69JGPY9JU6dZWNLLO12RlmCbWkp4oyR76ktdKb0XZq2dQ4VnHJG5Ge8YxcxZZkC+XaWaWMu61itsAYdzdbjNDlZLhudf0nVlaCtvvEmgGWLP8Cmy0i5HKivsb3pW7gignlxhlgUPBp0alI+5TLLIwhPIP15VAyyaZUkrRggp9dSCwUTOaCzLquN44IPqGsyQTFfmhy5e/GowhmpPmkaemgBGZBqEcQzJLMmghy0nzmdk2htO24eSNfTlB7y9HqYzta7Uf+1VOPO8N8WayGJ0dS3ICpBLfApVVgH9XSAxM7sQ4cHIy8vycr283BAfz1x59tv1pNKCb2vLVyDPb8NBiBVm5ui1oGjNqG3bpCrfERvL85H+17e30I+HJG8yasEdRe7hmlNXWz4boxbyPMgX/NBqbX2e0NEoxwRtqEvB93jxwoHCpL5llABg4NSPThCoPXM7xscMn/M/h/cQZv2dHSkz2sBOPSoaTWfjYN3HWLM9cDdrDXXYSFY7n4FufzMTN0rcVi4ZZ/r0k3GN/eRThjmrOxQ+ft3SLCglhOGuPbOT5QgzGeBHx1rpwhTlzUntu3+9YiWp7oZRlV9ruym0TsAo1RmBXiOZa+yaFmj45N2SPG6D9FfJU7Ab82R8HktPZNBYNO9/sbqPUS1A==
+api: eJztV21v2zYQ/iuH+5QEstOmGDDo07zEadW0iWsnDYYoSGnpbLGhSJWknAiGgf2I/cL9koGk/BLXbdBhH4Zh+RKJujvey3PPneeYk8k0ryxXEmPsCaEeDDAJvUEC99RAoUROGqwCTTN1T2AL4hrUg3Sfu3BZEGRMCNJQ1sZCpdWM55RKWxBMaiFWlgxlmiww42TUBNQEKmUMGcOV7MKoriqlrQFuTE35Us2kkskceOk+Uu6PuvD2+hLccckyppWSYNU9SQMZk1JZGBMYEpNOcDmHPVtQk0qmCYxllgQZs99NZSqd+4Nh8jF513/dv7tOLt+cDHvX56CJGSWBG3D2mEsL5TBRem04Yy5pqdxjecllR0nRBJufPn0qrK1SObgYXcLh7IiJqmAvD1nFz6gxsbMw9J6lcp5KgBQzTTlJy5lIMYYUzf2d4DO6Y+Ps5dGrbrebYhQkg2NBatj/eHHcu0wuzu+G/d7o4vzurP/b3fHF+8Hw4n0y6qeYyoX3ByNUFWnvcZJjjOH+3iA5owYj1PSlJmN/VXmD8RwzJS1J6x5ZVQkeQj38bBxI5miygkrmnp6iZ7QKLBgeBqshfT+AqlSOmxZIXE5hhaTnUYQRVtpFajkZH8kqse7NcisIYzzdgUuln4AM9ob9D1fJsH+yjxHapnJ6xmoup7iI2jKEFExYLazL6VfluDofDfrHyWnSP8FoK1nDFYSGAWtt5xgwVteZrTXlsMZZi0gDXJqKu2/jBoanx/DT0c8vuqm8MpQDlzBWtgCPSN8gW2iFiauERyl04GuHd7RCDL0VvuMn3cDltnmMkGRdYnzzbDKew+5Okd7pafIuCUfHb3rnr79hanQ16A9H/ZNvfN4RJd5uFzlaoWXZwNsVw8VipaTGnymzO5S+0RO4cMr/wvZxTODghbHVNUX42FGaT7lkYsA0K89Z6aIbO6LwbWAqJU3otaMXL/5R8gimHQdrsrWWlIOSYOosI2MmtdhGn4d1v6xssyGHf6dE4eZdNept3r+MvoteruWBH8jAFlepnNz/idIlc4TCpX11tA6AS0tT0uEyy7jwWtxS6R9YnnN3DxODTbOLbUr8JZibb5Pad8BcaWXVuJ70pK96K8a0Zv69JGPY9Adt6iobWWZrszPNEmpJjxVljo5Ja6U3s+3MsqlxPOOKNyI94xm5Hi7JFsoNuEoZd1vFbIExfm8IY4SuMsP1COw/srIStD0/1sywZP9nWG4RIZcT9TXWL3QDl0wot+wAg4JPi05F2hdeZmFJ4RmsL4eSSTalkqQFE6LtQmKhYDIXZNY9vqEi+ISyJhMU+5XKUYFbniKYkeaTpqWGEpgFoR5AMEsyayLISfOZ+2oKpW3H7SH5cr/aWy5e79vFaz/yr56GnA7zzbFarRxhcQOmEtwCl1aBfVDLCEzsxDpwcDDy8R6vfDcHB/Dn73+0c2y1uZjYc9gqMNjzu2IEWrmtLmrZMGoHeRsKtc5H8Pb6bLTv/fUp4MsNzruwxlF7uWeX1tXNQeyWwI00By42G8heV7c3SDDCGWkT6r5EoUOGA2jJPCHIQKoBjj5nYSt7ApoNWvl/Tf/vruktXVp6tIeVYFw6rNTar6+BzG7WMIpwB53dRlg48otvcD4fM0NXWiwW7vhLTbrB+OY2whnTnI0dXG9uFxEWxHLSGN/M8Z4ajPE4YK1z6dxx4qL2lL89zhbRUqOXZVTZ78pu8rNLOkZhkYjnWPrZh5o9OHplDxij/83i294J+LM5CiantZ81GGy6v78ArPkkpA==
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import OperationTabs from "@theme/OperationTabs"
-import TabItem from "@theme/TabItem"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+import Translate from "@docusaurus/Translate";
+
+
+
+
+
+
+
-
-
-Allows an API key holder to revoke their own key. The caller must provide the full API key secret as proof of possession. Supports
-issued API keys and imported keys. JWT and macaroon tokens cannot be self-revoked (they are stateless).
+Allows an API key holder to revoke their own key. The caller must provide
+the full API key secret as proof of possession. Supports issued API keys
+and imported keys. JWT and macaroon tokens cannot be self-revoked (they
+are stateless).
-The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
+The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation
+(admin-only).
```http
-POST /v2/apiKeys:selfRevoke
+POST /v2alpha1/apiKeys:selfRevoke
{
"credential": "sk_live_abc123...",
"reason": "REVOCATION_REASON_KEY_COMPROMISE"
}
```
-
+
Request
-
+
+
+
+
+
+
+
+
+
+
+
-
-
+
\ No newline at end of file
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
index 80b2017240..9551b2780c 100644
--- a/docs/talos/reference/api/sidebar.ts
+++ b/docs/talos/reference/api/sidebar.ts
@@ -1,4 +1,4 @@
-import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
const sidebar: SidebarsConfig = {
apisidebar: [
@@ -112,18 +112,6 @@ const sidebar: SidebarsConfig = {
type: "category",
label: "SelfService",
items: [
- {
- type: "doc",
- id: "reference/api/batch-verify-api-keys",
- label: "Batch Verify API Keys",
- className: "api-method post",
- },
- {
- type: "doc",
- id: "reference/api/verify-api-key",
- label: "Verify API Key",
- className: "api-method post",
- },
{
type: "doc",
id: "reference/api/revoke-api-key",
@@ -133,6 +121,6 @@ const sidebar: SidebarsConfig = {
],
},
],
-}
+};
-export default sidebar.apisidebar
+export default sidebar.apisidebar;
diff --git a/docs/talos/reference/api/verify-api-key.api.mdx b/docs/talos/reference/api/verify-api-key.api.mdx
deleted file mode 100644
index f9a6f876b4..0000000000
--- a/docs/talos/reference/api/verify-api-key.api.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: verify-api-key
-title: "Verify API Key"
-description: "Verifies a single credential (API key, JWT, or macaroon). Returns whether"
-sidebar_label: "Verify API Key"
-hide_title: true
-hide_table_of_contents: true
-sidebar_class_name: "post api-method"
-info_path: reference/api/ory-talos-api
-custom_edit_url: null
----
-
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
-import ParamsDetails from "@theme/ParamsDetails"
-import RequestSchema from "@theme/RequestSchema"
-import StatusCodes from "@theme/StatusCodes"
-import Heading from "@theme/Heading"
-import Translate from "@docusaurus/Translate"
-
-
-
-
-
-Verifies a single credential (API key, JWT, or macaroon). Returns whether the credential is active along with associated metadata.
-Results are cached for low-latency repeated verifications; use the `Cache-Control: no-cache` header to bypass the cache.
-
-```http
-POST /v2/apiKeys:verify
-{
- "credential": "sk_live_abc123..."
-}
-```
-
-
- Request
-
-
-
-
-
-
-
diff --git a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
index 87cb58eefa..a7c1557d43 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
@@ -9,15 +9,15 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk generate ecdsa
Generate an ECDSA key pair
### Synopsis
-Generate an ECDSA key pair using the specified elliptic curve. Key size is determined by the curve: P-256 (256-bit), P-384
-(384-bit), P-521 (521-bit). Default curve: P-256.
+Generate an ECDSA key pair using the specified elliptic curve.
+Key size is determined by the curve: P-256 (256-bit), P-384 (384-bit), P-521 (521-bit).
+Default curve: P-256.
```
talos jwk generate ecdsa [flags]
@@ -57,4 +57,5 @@ talos jwk generate ecdsa [flags]
### See also
-- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
+* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
+
diff --git a/docs/talos/reference/cli/talos-jwk-generate-eddsa.md b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
index 6567b04937..12bc60a75f 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
@@ -9,14 +9,14 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk generate eddsa
Generate an EdDSA (Ed25519) key pair
### Synopsis
-Generate an EdDSA key pair using the Ed25519 curve. Ed25519 uses a fixed 256-bit key size.
+Generate an EdDSA key pair using the Ed25519 curve.
+Ed25519 uses a fixed 256-bit key size.
```
talos jwk generate eddsa [flags]
@@ -58,4 +58,5 @@ talos jwk generate eddsa [flags]
### See also
-- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
+* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
+
diff --git a/docs/talos/reference/cli/talos-jwk-generate-hmac.md b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
index a3555d0ffe..660a65d016 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-hmac.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
@@ -9,15 +9,15 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk generate hmac
Generate an HMAC secret key
### Synopsis
-Generate a symmetric HMAC secret key. Default size is 512 bits. Minimum is 256 bits. Algorithm is determined by key size:
-256→HS256, 384→HS384, ≥512→HS512.
+Generate a symmetric HMAC secret key.
+Default size is 512 bits. Minimum is 256 bits.
+Algorithm is determined by key size: 256→HS256, 384→HS384, ≥512→HS512.
```
talos jwk generate hmac [flags]
@@ -56,4 +56,5 @@ talos jwk generate hmac [flags]
### See also
-- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
+* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
+
diff --git a/docs/talos/reference/cli/talos-jwk-generate-rsa.md b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
index 8057e5fc51..18685d9ee5 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-rsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
@@ -9,14 +9,14 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk generate rsa
Generate an RSA key pair
### Synopsis
-Generate an RSA key pair with the specified key size. Default is 2048 bits. Minimum is 2048 bits.
+Generate an RSA key pair with the specified key size.
+Default is 2048 bits. Minimum is 2048 bits.
```
talos jwk generate rsa [flags]
@@ -60,4 +60,5 @@ talos jwk generate rsa [flags]
### See also
-- [talos jwk generate](talos-jwk-generate) Generate a new JWK key
+* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
+
diff --git a/docs/talos/reference/cli/talos-jwk-generate.md b/docs/talos/reference/cli/talos-jwk-generate.md
index eb6aded4f9..c6ebfa524c 100644
--- a/docs/talos/reference/cli/talos-jwk-generate.md
+++ b/docs/talos/reference/cli/talos-jwk-generate.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk generate
Generate a new JWK key
@@ -33,8 +32,9 @@ Generate a new cryptographic key in JWK format for signing or encryption.
### See also
-- [talos jwk](talos-jwk) Generate JSON Web Keys (JWK/JWKS)
-- [talos jwk generate ecdsa](talos-jwk-generate-ecdsa) - Generate an ECDSA key pair
-- [talos jwk generate eddsa](talos-jwk-generate-eddsa) - Generate an EdDSA (Ed25519) key pair
-- [talos jwk generate hmac](talos-jwk-generate-hmac) - Generate an HMAC secret key
-- [talos jwk generate rsa](talos-jwk-generate-rsa) - Generate an RSA key pair
+* [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
+* [talos jwk generate ecdsa](talos-jwk-generate-ecdsa.md) - Generate an ECDSA key pair
+* [talos jwk generate eddsa](talos-jwk-generate-eddsa.md) - Generate an EdDSA (Ed25519) key pair
+* [talos jwk generate hmac](talos-jwk-generate-hmac.md) - Generate an HMAC secret key
+* [talos jwk generate rsa](talos-jwk-generate-rsa.md) - Generate an RSA key pair
+
diff --git a/docs/talos/reference/cli/talos-jwk-get.md b/docs/talos/reference/cli/talos-jwk-get.md
index a50284863d..49576b158c 100644
--- a/docs/talos/reference/cli/talos-jwk-get.md
+++ b/docs/talos/reference/cli/talos-jwk-get.md
@@ -9,15 +9,33 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk get
Fetch the server's JSON Web Key Set (JWKS)
+### Synopsis
+
+Fetch the public signing keys used to verify derived JWT tokens.
+
+The JWKS is served at GET /v2alpha1/admin/derivedKeys/jwks.json and includes the active
+signing key plus any retired keys still inside the verification window.
+
+Clients verifying derived tokens should cache the response for 5 to 15 minutes and
+refetch when they encounter a token with an unknown 'kid'. Polling more aggressively does
+not shorten the practical revocation window — that window is bounded by the longest
+issued token TTL, not by the JWKS cache.
+
```
talos jwk get [flags]
```
+### Examples
+
+```
+ # Pretty-print the JWKS served by a local Talos
+ talos jwk get -e http://localhost:4420 | jq .
+```
+
### Options
```
@@ -33,4 +51,5 @@ talos jwk get [flags]
### See also
-- [talos jwk](talos-jwk) Generate JSON Web Keys (JWK/JWKS)
+* [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
+
diff --git a/docs/talos/reference/cli/talos-jwk.md b/docs/talos/reference/cli/talos-jwk.md
index cd67984282..4bd1673a2a 100644
--- a/docs/talos/reference/cli/talos-jwk.md
+++ b/docs/talos/reference/cli/talos-jwk.md
@@ -9,15 +9,14 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos jwk
Generate JSON Web Keys (JWK/JWKS)
### Synopsis
-Generate cryptographic keys in JSON Web Key (JWK) format. Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC
-algorithms.
+Generate cryptographic keys in JSON Web Key (JWK) format.
+Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC algorithms.
### Options
@@ -34,6 +33,7 @@ algorithms.
### See also
-- [talos](talos) High-performance multi-network API key service
-- [talos jwk generate](talos-jwk-generate) - Generate a new JWK key
-- [talos jwk get](talos-jwk-get) - Fetch the server's JSON Web Key Set (JWKS)
+* [talos](talos.md) Multi-tenant API key management service
+* [talos jwk generate](talos-jwk-generate.md) - Generate a new JWK key
+* [talos jwk get](talos-jwk-get.md) - Fetch the server's JSON Web Key Set (JWKS)
+
diff --git a/docs/talos/reference/cli/talos-keys-batch-verify.md b/docs/talos/reference/cli/talos-keys-batch-verify.md
index 39d99b1585..33ad2aa115 100644
--- a/docs/talos/reference/cli/talos-keys-batch-verify.md
+++ b/docs/talos/reference/cli/talos-keys-batch-verify.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys batch-verify
Verify multiple credentials in a single request
@@ -36,4 +35,5 @@ talos keys batch-verify [credentials...] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-derive-token.md b/docs/talos/reference/cli/talos-keys-derive-token.md
index 2a208b8ea6..aac5bf037b 100644
--- a/docs/talos/reference/cli/talos-keys-derive-token.md
+++ b/docs/talos/reference/cli/talos-keys-derive-token.md
@@ -9,14 +9,13 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys derive-token
-Derive a new derived token from an existing API key
+Derive a short-lived JWT or macaroon from an existing API key
### Synopsis
-Derives a new short-lived derived token from an existing opaque API key. The output will be a JWT or Macaroon token.
+Derives a short-lived JWT or macaroon token from an existing opaque API key.
```
talos keys derive-token [api-key-token] [flags]
@@ -42,4 +41,5 @@ talos keys derive-token [api-key-token] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-batch-import.md b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
index 6ffd8296fa..186c348431 100644
--- a/docs/talos/reference/cli/talos-keys-imported-batch-import.md
+++ b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported batch-import
Batch import API keys from a JSON file
@@ -40,4 +39,5 @@ talos keys imported batch-import --file keys.json [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-delete.md b/docs/talos/reference/cli/talos-keys-imported-delete.md
index 96bb8fd95a..dce11140ff 100644
--- a/docs/talos/reference/cli/talos-keys-imported-delete.md
+++ b/docs/talos/reference/cli/talos-keys-imported-delete.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported delete
Permanently delete an imported API key
@@ -35,4 +34,5 @@ talos keys imported delete [key-id] [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-get.md b/docs/talos/reference/cli/talos-keys-imported-get.md
index fb3e848021..812438b755 100644
--- a/docs/talos/reference/cli/talos-keys-imported-get.md
+++ b/docs/talos/reference/cli/talos-keys-imported-get.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported get
Get details of an imported API key
@@ -35,4 +34,5 @@ talos keys imported get [key-id] [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-import.md b/docs/talos/reference/cli/talos-keys-imported-import.md
index adff651e8d..49053abb84 100644
--- a/docs/talos/reference/cli/talos-keys-imported-import.md
+++ b/docs/talos/reference/cli/talos-keys-imported-import.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported import
Import an external API key
@@ -43,4 +42,5 @@ talos keys imported import [name] [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-list.md b/docs/talos/reference/cli/talos-keys-imported-list.md
index 405adc8ff0..49fcca7548 100644
--- a/docs/talos/reference/cli/talos-keys-imported-list.md
+++ b/docs/talos/reference/cli/talos-keys-imported-list.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported list
List imported API keys
@@ -39,4 +38,5 @@ talos keys imported list [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported-revoke.md b/docs/talos/reference/cli/talos-keys-imported-revoke.md
index 5eb5cc2cd7..cd4cce9d4f 100644
--- a/docs/talos/reference/cli/talos-keys-imported-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-imported-revoke.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported revoke
Revoke an imported API key
@@ -37,4 +36,5 @@ talos keys imported revoke [key-id] [flags]
### See also
-- [talos keys imported](talos-keys-imported) Manage imported API keys
+* [talos keys imported](talos-keys-imported.md) Manage imported API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-imported.md b/docs/talos/reference/cli/talos-keys-imported.md
index e79c86e531..68368497b1 100644
--- a/docs/talos/reference/cli/talos-keys-imported.md
+++ b/docs/talos/reference/cli/talos-keys-imported.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys imported
Manage imported API keys
@@ -35,10 +34,11 @@ Import, list, get, revoke, and delete externally-created API keys.
### See also
-- [talos keys](talos-keys) Manage API keys
-- [talos keys imported batch-import](talos-keys-imported-batch-import) - Batch import API keys from a JSON file
-- [talos keys imported delete](talos-keys-imported-delete) - Permanently delete an imported API key
-- [talos keys imported get](talos-keys-imported-get) - Get details of an imported API key
-- [talos keys imported import](talos-keys-imported-import) - Import an external API key
-- [talos keys imported list](talos-keys-imported-list) - List imported API keys
-- [talos keys imported revoke](talos-keys-imported-revoke) - Revoke an imported API key
+* [talos keys](talos-keys.md) Manage API keys
+* [talos keys imported batch-import](talos-keys-imported-batch-import.md) - Batch import API keys from a JSON file
+* [talos keys imported delete](talos-keys-imported-delete.md) - Permanently delete an imported API key
+* [talos keys imported get](talos-keys-imported-get.md) - Get details of an imported API key
+* [talos keys imported import](talos-keys-imported-import.md) - Import an external API key
+* [talos keys imported list](talos-keys-imported-list.md) - List imported API keys
+* [talos keys imported revoke](talos-keys-imported-revoke.md) - Revoke an imported API key
+
diff --git a/docs/talos/reference/cli/talos-keys-issue.md b/docs/talos/reference/cli/talos-keys-issue.md
index bfc1dc6195..9975657106 100644
--- a/docs/talos/reference/cli/talos-keys-issue.md
+++ b/docs/talos/reference/cli/talos-keys-issue.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issue
Issue a new API key
@@ -42,4 +41,5 @@ talos keys issue [name] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued-get.md b/docs/talos/reference/cli/talos-keys-issued-get.md
index 287a81acea..607691f73e 100644
--- a/docs/talos/reference/cli/talos-keys-issued-get.md
+++ b/docs/talos/reference/cli/talos-keys-issued-get.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued get
Get details of an issued API key
@@ -35,4 +34,5 @@ talos keys issued get [key-id] [flags]
### See also
-- [talos keys issued](talos-keys-issued) Manage issued API keys
+* [talos keys issued](talos-keys-issued.md) Manage issued API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued-issue.md b/docs/talos/reference/cli/talos-keys-issued-issue.md
index f1821c17c7..80191ebd5f 100644
--- a/docs/talos/reference/cli/talos-keys-issued-issue.md
+++ b/docs/talos/reference/cli/talos-keys-issued-issue.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued issue
Issue a new API key
@@ -42,4 +41,5 @@ talos keys issued issue [name] [flags]
### See also
-- [talos keys issued](talos-keys-issued) Manage issued API keys
+* [talos keys issued](talos-keys-issued.md) Manage issued API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued-list.md b/docs/talos/reference/cli/talos-keys-issued-list.md
index 137f0398d0..2c1904420e 100644
--- a/docs/talos/reference/cli/talos-keys-issued-list.md
+++ b/docs/talos/reference/cli/talos-keys-issued-list.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued list
List issued API keys
@@ -39,4 +38,5 @@ talos keys issued list [flags]
### See also
-- [talos keys issued](talos-keys-issued) Manage issued API keys
+* [talos keys issued](talos-keys-issued.md) Manage issued API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued-rotate.md b/docs/talos/reference/cli/talos-keys-issued-rotate.md
index df8c7783f8..1bd5645ba2 100644
--- a/docs/talos/reference/cli/talos-keys-issued-rotate.md
+++ b/docs/talos/reference/cli/talos-keys-issued-rotate.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued rotate
Rotate an issued API key (revokes old key, creates new one)
@@ -38,4 +37,5 @@ talos keys issued rotate [key-id] [flags]
### See also
-- [talos keys issued](talos-keys-issued) Manage issued API keys
+* [talos keys issued](talos-keys-issued.md) Manage issued API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued-update.md b/docs/talos/reference/cli/talos-keys-issued-update.md
index 4b49862269..deebf0fb86 100644
--- a/docs/talos/reference/cli/talos-keys-issued-update.md
+++ b/docs/talos/reference/cli/talos-keys-issued-update.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued update
Update an issued API key
@@ -41,4 +40,5 @@ talos keys issued update [key-id] [flags]
### See also
-- [talos keys issued](talos-keys-issued) Manage issued API keys
+* [talos keys issued](talos-keys-issued.md) Manage issued API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-issued.md b/docs/talos/reference/cli/talos-keys-issued.md
index b002b0f525..223ed0c57d 100644
--- a/docs/talos/reference/cli/talos-keys-issued.md
+++ b/docs/talos/reference/cli/talos-keys-issued.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys issued
Manage issued API keys
@@ -35,9 +34,10 @@ Get, list, update, and rotate issued API keys.
### See also
-- [talos keys](talos-keys) Manage API keys
-- [talos keys issued get](talos-keys-issued-get) - Get details of an issued API key
-- [talos keys issued issue](talos-keys-issued-issue) - Issue a new API key
-- [talos keys issued list](talos-keys-issued-list) - List issued API keys
-- [talos keys issued rotate](talos-keys-issued-rotate) - Rotate an issued API key (revokes old key, creates new one)
-- [talos keys issued update](talos-keys-issued-update) - Update an issued API key
+* [talos keys](talos-keys.md) Manage API keys
+* [talos keys issued get](talos-keys-issued-get.md) - Get details of an issued API key
+* [talos keys issued issue](talos-keys-issued-issue.md) - Issue a new API key
+* [talos keys issued list](talos-keys-issued-list.md) - List issued API keys
+* [talos keys issued rotate](talos-keys-issued-rotate.md) - Rotate an issued API key (revokes old key, creates new one)
+* [talos keys issued update](talos-keys-issued-update.md) - Update an issued API key
+
diff --git a/docs/talos/reference/cli/talos-keys-revoke.md b/docs/talos/reference/cli/talos-keys-revoke.md
index 89d87a6f5b..18ee6a8392 100644
--- a/docs/talos/reference/cli/talos-keys-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-revoke.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys revoke
Revoke an API key
@@ -36,4 +35,5 @@ talos keys revoke [key-id] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-self-revoke.md b/docs/talos/reference/cli/talos-keys-self-revoke.md
index 22b72b3e8f..f453166adb 100644
--- a/docs/talos/reference/cli/talos-keys-self-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-self-revoke.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys self-revoke
Revoke an API key using the credential itself as proof
@@ -40,4 +39,5 @@ talos keys self-revoke [credential] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys-verify.md b/docs/talos/reference/cli/talos-keys-verify.md
index 2ab4a5443c..9f9edbe1d1 100644
--- a/docs/talos/reference/cli/talos-keys-verify.md
+++ b/docs/talos/reference/cli/talos-keys-verify.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys verify
Verify a credential (API key or token)
@@ -40,4 +39,5 @@ talos keys verify [credential] [flags]
### See also
-- [talos keys](talos-keys) Manage API keys
+* [talos keys](talos-keys.md) Manage API keys
+
diff --git a/docs/talos/reference/cli/talos-keys.md b/docs/talos/reference/cli/talos-keys.md
index 5f0e27a233..4798a62425 100644
--- a/docs/talos/reference/cli/talos-keys.md
+++ b/docs/talos/reference/cli/talos-keys.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos keys
Manage API keys
@@ -35,12 +34,13 @@ Create, list, get, revoke, and rotate API keys.
### See also
-- [talos](talos) High-performance multi-network API key service
-- [talos keys batch-verify](talos-keys-batch-verify) - Verify multiple credentials in a single request
-- [talos keys derive-token](talos-keys-derive-token) - Derive a new derived token from an existing API key
-- [talos keys imported](talos-keys-imported) - Manage imported API keys
-- [talos keys issue](talos-keys-issue) - Issue a new API key
-- [talos keys issued](talos-keys-issued) - Manage issued API keys
-- [talos keys revoke](talos-keys-revoke) - Revoke an API key
-- [talos keys self-revoke](talos-keys-self-revoke) - Revoke an API key using the credential itself as proof
-- [talos keys verify](talos-keys-verify) - Verify a credential (API key or token)
+* [talos](talos.md) Multi-tenant API key management service
+* [talos keys batch-verify](talos-keys-batch-verify.md) - Verify multiple credentials in a single request
+* [talos keys derive-token](talos-keys-derive-token.md) - Derive a short-lived JWT or macaroon from an existing API key
+* [talos keys imported](talos-keys-imported.md) - Manage imported API keys
+* [talos keys issue](talos-keys-issue.md) - Issue a new API key
+* [talos keys issued](talos-keys-issued.md) - Manage issued API keys
+* [talos keys revoke](talos-keys-revoke.md) - Revoke an API key
+* [talos keys self-revoke](talos-keys-self-revoke.md) - Revoke an API key using the credential itself as proof
+* [talos keys verify](talos-keys-verify.md) - Verify a credential (API key or token)
+
diff --git a/docs/talos/reference/cli/talos-migrate-down.md b/docs/talos/reference/cli/talos-migrate-down.md
index b6a04026fb..8a15ec3802 100644
--- a/docs/talos/reference/cli/talos-migrate-down.md
+++ b/docs/talos/reference/cli/talos-migrate-down.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos migrate down
Rollback migrations
@@ -18,7 +17,8 @@ Rollback migrations
Roll back the last N migrations (default: 1).
-This is useful for reverting recent migrations in development. In production, use this carefully and ensure you have backups.
+This is useful for reverting recent migrations in development.
+In production, use this carefully and ensure you have backups.
```
talos migrate down [flags]
@@ -51,4 +51,5 @@ talos migrate down [flags]
### See also
-- [talos migrate](talos-migrate) Database migration tools
+* [talos migrate](talos-migrate.md) Database migration tools
+
diff --git a/docs/talos/reference/cli/talos-migrate-force.md b/docs/talos/reference/cli/talos-migrate-force.md
index 1748ac4c57..df5775f5b3 100644
--- a/docs/talos/reference/cli/talos-migrate-force.md
+++ b/docs/talos/reference/cli/talos-migrate-force.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos migrate force
Force set migration version (use with caution)
@@ -19,12 +18,12 @@ Force set migration version (use with caution)
Force the migration version to a specific value.
This is useful when:
+ - A migration failed and left the database in a dirty state
+ - You need to manually fix the database state
+ - You want to mark a migration as applied without running it
-- A migration failed and left the database in a dirty state
-- You need to manually fix the database state
-- You want to mark a migration as applied without running it
-
-WARNING: This command should be used carefully as it can lead to inconsistent database state if used incorrectly.
+WARNING: This command should be used carefully as it can lead to
+inconsistent database state if used incorrectly.
```
talos migrate force VERSION [flags]
@@ -53,4 +52,5 @@ talos migrate force VERSION [flags]
### See also
-- [talos migrate](talos-migrate) Database migration tools
+* [talos migrate](talos-migrate.md) Database migration tools
+
diff --git a/docs/talos/reference/cli/talos-migrate-status.md b/docs/talos/reference/cli/talos-migrate-status.md
index 7ba3945f05..7d58414536 100644
--- a/docs/talos/reference/cli/talos-migrate-status.md
+++ b/docs/talos/reference/cli/talos-migrate-status.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos migrate status
Show migration status
@@ -19,10 +18,9 @@ Show migration status
Display the current database migration status.
Shows:
-
-- Current migration version
-- Whether the database is in a dirty state
-- Database connection info
+ - Current migration version
+ - Whether the database is in a dirty state
+ - Database connection info
```
talos migrate status [flags]
@@ -44,4 +42,5 @@ talos migrate status [flags]
### See also
-- [talos migrate](talos-migrate) Database migration tools
+* [talos migrate](talos-migrate.md) Database migration tools
+
diff --git a/docs/talos/reference/cli/talos-migrate-up.md b/docs/talos/reference/cli/talos-migrate-up.md
index 83be0a7908..9c1cf6966d 100644
--- a/docs/talos/reference/cli/talos-migrate-up.md
+++ b/docs/talos/reference/cli/talos-migrate-up.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos migrate up
Run all pending migrations
@@ -19,9 +18,8 @@ Run all pending migrations
Apply all pending migrations to the database.
The database connection string can be provided via:
-
-- DB_DSN environment variable
-- --database flag (overrides DB_DSN)
+ - DB_DSN environment variable
+ - --database flag (overrides DB_DSN)
```
talos migrate up [flags]
@@ -60,4 +58,5 @@ talos migrate up [flags]
### See also
-- [talos migrate](talos-migrate) Database migration tools
+* [talos migrate](talos-migrate.md) Database migration tools
+
diff --git a/docs/talos/reference/cli/talos-migrate.md b/docs/talos/reference/cli/talos-migrate.md
index 9173facd32..0d26134f47 100644
--- a/docs/talos/reference/cli/talos-migrate.md
+++ b/docs/talos/reference/cli/talos-migrate.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos migrate
Database migration tools
@@ -33,8 +32,9 @@ Run database migrations for the API Key service
### See also
-- [talos](talos) High-performance multi-network API key service
-- [talos migrate down](talos-migrate-down) - Rollback migrations
-- [talos migrate force](talos-migrate-force) - Force set migration version (use with caution)
-- [talos migrate status](talos-migrate-status) - Show migration status
-- [talos migrate up](talos-migrate-up) - Run all pending migrations
+* [talos](talos.md) Multi-tenant API key management service
+* [talos migrate down](talos-migrate-down.md) - Rollback migrations
+* [talos migrate force](talos-migrate-force.md) - Force set migration version (use with caution)
+* [talos migrate status](talos-migrate-status.md) - Show migration status
+* [talos migrate up](talos-migrate-up.md) - Run all pending migrations
+
diff --git a/docs/talos/reference/cli/talos-proxy.md b/docs/talos/reference/cli/talos-proxy.md
index 16f81709b2..75e87cd681 100644
--- a/docs/talos/reference/cli/talos-proxy.md
+++ b/docs/talos/reference/cli/talos-proxy.md
@@ -9,23 +9,46 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos proxy
-Start the edge proxy (commercial edition only)
+Start the edge proxy for caching verification requests
### Synopsis
-The proxy command is only available in the commercial edition.
+Start an edge proxy that caches verification responses from an upstream Talos server.
+
+The proxy caches successful verification responses to reduce latency and load on the upstream server.
+Only active (valid) verification responses are cached.
+
+Cache bypass: Clients can bypass the cache by sending Cache-Control: no-cache header.
+
+The proxy exposes health endpoints:
+ /health/alive - Always returns 200 OK
+ /health/ready - Returns 200 OK if upstream is reachable
```
talos proxy [flags]
```
+### Examples
+
+```
+ talos proxy --upstream http://talos:8080
+ talos proxy --upstream http://talos:8080 --listen :9090 --cache-ttl 5m
+ talos proxy --upstream http://talos:8080 --trust-x-forwarded-host
+```
+
### Options
```
- -h, --help help for proxy
+ --allowed-hosts strings Allowlist of valid Host/X-Forwarded-Host values (if set, requests with other hosts are rejected with 403)
+ --cache-max-size int Maximum cache size in bytes (default 104857600)
+ --cache-num-counters int Number of frequency counters for cache admission (default 10000)
+ --cache-ttl duration Cache entry TTL (default 1m0s)
+ -h, --help help for proxy
+ --listen string Listen address for the proxy (default ":8080")
+ --trust-x-forwarded-host Trust X-Forwarded-Host header for multi-tenant cache isolation (use when behind a trusted load balancer)
+ --upstream string Upstream Talos server URL (required)
```
### Options inherited from parent commands
@@ -37,4 +60,5 @@ talos proxy [flags]
### See also
-- [talos](talos) High-performance multi-network API key service
+* [talos](talos.md) Multi-tenant API key management service
+
diff --git a/docs/talos/reference/cli/talos-serve-admin.md b/docs/talos/reference/cli/talos-serve-admin.md
index 9aacdf0819..dea6b38d04 100644
--- a/docs/talos/reference/cli/talos-serve-admin.md
+++ b/docs/talos/reference/cli/talos-serve-admin.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos serve admin
Start the admin plane server (management only)
@@ -18,11 +17,10 @@ Start the admin plane server (management only)
Starts the admin plane server for API key and network management.
-This mode runs only the management endpoints for administrative operations. It's designed for internal tools, CI/CD, and
-administrative access.
+This mode runs only the management endpoints for administrative operations.
+It's designed for internal tools, CI/CD, and administrative access.
Features:
-
- Full read/write database access
- API key creation, rotation, revocation
- Network management
@@ -54,4 +52,5 @@ talos serve admin [flags]
### See also
-- [talos serve](talos-serve) Start the Ory Talos server (all-in-one mode)
+* [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
+
diff --git a/docs/talos/reference/cli/talos-serve-check.md b/docs/talos/reference/cli/talos-serve-check.md
index 400bb513ef..33bbef15c4 100644
--- a/docs/talos/reference/cli/talos-serve-check.md
+++ b/docs/talos/reference/cli/talos-serve-check.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos serve check
Start the data plane server (verification only)
@@ -18,8 +17,8 @@ Start the data plane server (verification only)
Starts the data plane server for API key and token verification.
-This mode runs only the verification endpoints with caching for optimal read performance. It's designed for edge deployments and
-high-throughput verification workloads.
+This mode runs only the verification endpoints with caching for optimal read performance.
+It's designed for edge deployments and high-throughput verification workloads.
Cache configuration is read from the config file (cache.type, cache.ttl, etc.)
@@ -48,4 +47,5 @@ talos serve check [flags]
### See also
-- [talos serve](talos-serve) Start the Ory Talos server (all-in-one mode)
+* [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
+
diff --git a/docs/talos/reference/cli/talos-serve.md b/docs/talos/reference/cli/talos-serve.md
index 81dc4a1ec1..8f6eb9f6aa 100644
--- a/docs/talos/reference/cli/talos-serve.md
+++ b/docs/talos/reference/cli/talos-serve.md
@@ -9,7 +9,6 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos serve
Start the Ory Talos server (all-in-one mode)
@@ -21,9 +20,8 @@ Starts the HTTP server for the API key service in all-in-one mode.
This mode runs both admin plane (management) and data plane (verification) in a single process.
For production deployments with high-throughput verification workloads, consider using:
-
-- 'serve check' for data plane only (verification with caching)
-- 'serve admin' for admin plane only (management operations)
+- `serve check` for data plane only (verification with caching)
+- `serve admin` for admin plane only (management operations)
```
talos serve [flags]
@@ -50,6 +48,7 @@ talos serve [flags]
### See also
-- [talos](talos) High-performance multi-network API key service
-- [talos serve admin](talos-serve-admin) - Start the admin plane server (management only)
-- [talos serve check](talos-serve-check) - Start the data plane server (verification only)
+* [talos](talos.md) Multi-tenant API key management service
+* [talos serve admin](talos-serve-admin.md) - Start the admin plane server (management only)
+* [talos serve check](talos-serve-check.md) - Start the data plane server (verification only)
+
diff --git a/docs/talos/reference/cli/talos.md b/docs/talos/reference/cli/talos.md
index 55ed780892..9e5ca65ecb 100644
--- a/docs/talos/reference/cli/talos.md
+++ b/docs/talos/reference/cli/talos.md
@@ -9,17 +9,17 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
-
## talos
-High-performance multi-network API key service
+Multi-tenant API key management service
### Synopsis
-API Key Service is a high-performance, multi-network service for managing API keys with support for JWT tokens, JWKS, and various
-cryptographic algorithms.
-
-It provides both admin plane and data plane APIs for comprehensive key management.
+Ory Talos manages the full lifecycle of API credentials: issuing keys,
+verifying them at low latency, deriving short-lived JWT or macaroon tokens,
+and revoking access. It exposes a separate admin plane (issue, rotate,
+revoke, derive) and data plane (verify, self-revoke) so each can be scaled
+and secured independently.
### Options
@@ -31,8 +31,9 @@ It provides both admin plane and data plane APIs for comprehensive key managemen
### See also
-- [talos jwk](talos-jwk) - Generate JSON Web Keys (JWK/JWKS)
-- [talos keys](talos-keys) - Manage API keys
-- [talos migrate](talos-migrate) - Database migration tools
-- [talos proxy](talos-proxy) - Start the edge proxy (commercial edition only)
-- [talos serve](talos-serve) - Start the Ory Talos server (all-in-one mode)
+* [talos jwk](talos-jwk.md) - Generate JSON Web Keys (JWK/JWKS)
+* [talos keys](talos-keys.md) - Manage API keys
+* [talos migrate](talos-migrate.md) - Database migration tools
+* [talos proxy](talos-proxy.md) - Start the edge proxy for caching verification requests
+* [talos serve](talos-serve.md) - Start the Ory Talos server (all-in-one mode)
+
diff --git a/docs/talos/reference/config.md b/docs/talos/reference/config.md
index 1468b1aaee..3f74f0089f 100644
--- a/docs/talos/reference/config.md
+++ b/docs/talos/reference/config.md
@@ -5,25 +5,27 @@ description: Auto-generated configuration reference from JSON Schema
# Configuration reference
-This page is auto-generated from the [configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
+This page is auto-generated from the
+[configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
Required top-level keys: `credentials`, `secrets`
## Environment variables
-Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and converts dot-separated config
-paths to uppercase with underscores:
+Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and
+converts dot-separated config paths to uppercase with underscores:
```
TALOS__
```
-Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port` becomes
-`TALOS_SERVE_HTTP_PORT`.
+Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port`
+becomes `TALOS_SERVE_HTTP_PORT`.
### Array values
-For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed variables:
+For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed
+variables:
```bash
# Comma-separated
@@ -87,7 +89,7 @@ Credential configuration for API keys and derived tokens (JWT, macaroon).
| `credentials.api_keys.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_API_KEYS_PREFIX_RETIRED` | Retired prefixes accepted during verification for migration purposes. |
| `credentials.clock_skew` | string | `5m` | `TALOS_CREDENTIALS_CLOCK_SKEW` | Maximum clock skew tolerance for timestamp and token validation. |
| `credentials.derived_tokens.default_ttl` | string | `1h` | `TALOS_CREDENTIALS_DERIVED_TOKENS_DEFAULT_TTL` | Default derived token TTL applied to both JWT and macaroon tokens when no explicit TTL is provided in the request (duration string) |
-| `credentials.derived_tokens.jwt.signing_key_id` | string | "" | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEY_ID` | Preferred signing key ID (kid) to use when selecting a key from the configured JWKS. |
+| `credentials.derived_tokens.jwt.signing_key_id` | string | — | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEY_ID` | Optional JWK 'kid' hint used to select the active signing key. |
| `credentials.derived_tokens.jwt.signing_keys.urls` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_JWT_SIGNING_KEYS_URLS` | List of JWKS resources. |
| `credentials.derived_tokens.macaroon.prefix.current` | string | `mc` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_CURRENT` | Current prefix used for new macaroon token generation. |
| `credentials.derived_tokens.macaroon.prefix.retired` | string[] | `[]` | `TALOS_CREDENTIALS_DERIVED_TOKENS_MACAROON_PREFIX_RETIRED` | Retired prefixes accepted during macaroon verification for rotation purposes. |
@@ -172,19 +174,19 @@ Server configuration for HTTP and metrics endpoints.
| `serve.http.port` | integer | `4420` | `TALOS_SERVE_HTTP_PORT` | The port that the endpoint listens on. (restart required) |
| `serve.http.request_log.exclude_health_endpoints` | boolean | `false` | `TALOS_SERVE_HTTP_REQUEST_LOG_EXCLUDE_HEALTH_ENDPOINTS` | Exclude /health/alive and /health/ready endpoints from request logs |
| `serve.http.trust_forwarded_host` | boolean | `false` | `TALOS_SERVE_HTTP_TRUST_FORWARDED_HOST` | Trust the X-Forwarded-Host header for tenant routing. (restart required) |
-| `serve.metrics.host` | string | `0.0.0.0` | `TALOS_SERVE_METRICS_HOST` | The host (interface) that the metrics endpoint listens on. (restart required) |
-| `serve.metrics.port` | integer | `4422` | `TALOS_SERVE_METRICS_PORT` | The port that the metrics endpoint listens on. (restart required) |
+| `serve.metrics.host` | string | `0.0.0.0` | `TALOS_SERVE_METRICS_HOST` | The host (interface) that the metrics endpoint listens on. (restart required, Commercial) |
+| `serve.metrics.port` | integer | `4422` | `TALOS_SERVE_METRICS_PORT` | The port that the metrics endpoint listens on. (restart required, Commercial) |
-## `tracing` (restart required)
+## `tracing` Commercial (restart required)
OpenTelemetry tracing configuration.
-| Key | Type | Default | Env Var | Description |
-| ------------------------- | ------- | ------------- | ------------------------------- | ------------------------------------------------------------------ |
-| `tracing.enabled` | boolean | `false` | `TALOS_TRACING_ENABLED` | Enable tracing. (restart required) |
-| `tracing.endpoint` | string | — | `TALOS_TRACING_ENDPOINT` | Trace collector endpoint. (restart required) |
-| `tracing.environment` | string | `development` | `TALOS_TRACING_ENVIRONMENT` | Deployment environment tag in trace attributes. (restart required) |
-| `tracing.exporter` | `otlp` | — | `TALOS_TRACING_EXPORTER` | Trace exporter type. (restart required) |
-| `tracing.sample_rate` | number | `0.001` | `TALOS_TRACING_SAMPLE_RATE` | Sampling rate (0.0 to 1.0). (restart required) |
-| `tracing.service_name` | string | `talos` | `TALOS_TRACING_SERVICE_NAME` | Service name reported to OpenTelemetry. (restart required) |
-| `tracing.service_version` | string | `0.0.0` | `TALOS_TRACING_SERVICE_VERSION` | Service version reported to OpenTelemetry. (restart required) |
+| Key | Type | Default | Env Var | Description |
+| ------------------------- | ------- | ------------- | ------------------------------- | ------------------------------------------------------------------------------ |
+| `tracing.enabled` | boolean | `false` | `TALOS_TRACING_ENABLED` | Enable tracing. (restart required, Commercial) |
+| `tracing.endpoint` | string | — | `TALOS_TRACING_ENDPOINT` | Trace collector endpoint. (restart required, Commercial) |
+| `tracing.environment` | string | `development` | `TALOS_TRACING_ENVIRONMENT` | Deployment environment tag in trace attributes. (restart required, Commercial) |
+| `tracing.exporter` | `otlp` | — | `TALOS_TRACING_EXPORTER` | Trace exporter type. (restart required, Commercial) |
+| `tracing.sample_rate` | number | `0.001` | `TALOS_TRACING_SAMPLE_RATE` | Sampling rate (0.0 to 1.0). (restart required, Commercial) |
+| `tracing.service_name` | string | `talos` | `TALOS_TRACING_SERVICE_NAME` | Service name reported to OpenTelemetry. (restart required, Commercial) |
+| `tracing.service_version` | string | `0.0.0` | `TALOS_TRACING_SERVICE_VERSION` | Service version reported to OpenTelemetry. (restart required, Commercial) |
diff --git a/docs/talos/reference/error-codes.md b/docs/talos/reference/error-codes.md
index e17b22d3d1..b519ac3baf 100644
--- a/docs/talos/reference/error-codes.md
+++ b/docs/talos/reference/error-codes.md
@@ -4,12 +4,13 @@ description: HTTP and gRPC error codes returned by the Talos API
---
-
+
# Error codes
-Talos returns structured error responses following the [herodot](https://github.com/ory/herodot) error format. Every error
-response includes an `id`, HTTP status code, status text, and a human-readable message.
+Talos returns structured error responses following the [herodot](https://github.com/ory/herodot)
+error format. Every error response includes an `id`, HTTP status code, status text, and a
+human-readable message.
## Error response format
@@ -96,4 +97,5 @@ The `BatchImportAPIKeys` response includes per-item error codes:
- **4xx errors**: Fix the request and retry. Do not retry without changes.
- **409 Conflict**: Check if the resource already exists or is in an incompatible state.
- **5xx errors**: Retry with exponential backoff and jitter.
-- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After` header value if present.
+- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After`
+ header value if present.
diff --git a/docs/talos/reference/events.md b/docs/talos/reference/events.md
index 53c89a63c2..26b5d8751d 100644
--- a/docs/talos/reference/events.md
+++ b/docs/talos/reference/events.md
@@ -8,10 +8,12 @@ description: Structured audit events emitted by Talos via OpenTelemetry
# Audit events
-Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle operations. Events are attached to
-the active OTEL span and forwarded to any configured OTEL collector. They are never persisted locally.
+Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle
+operations. Events are attached to the active OTEL span and forwarded to any configured OTEL
+collector. They are never persisted locally.
-Each event carries a set of structured attributes that provide context about the operation, the actor, and the affected resource.
+Each event carries a set of structured attributes that provide context about the operation, the
+actor, and the affected resource.
## Event types
@@ -48,9 +50,9 @@ Each event carries the following OTEL span event attributes:
## Dynamic metadata attributes
-The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys are prefixed with `metadata.`
-in OTEL attributes. For example, a metadata entry `{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with
-value `jwt`.
+The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys
+are prefixed with `metadata.` in OTEL attributes. For example, a metadata entry
+`{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with value `jwt`.
Metadata is optional and varies by event type. Common metadata keys include:
@@ -73,4 +75,5 @@ events.New(events.EventAPIKeyCreated).
Emit(ctx, emitter)
```
-Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently dropped.
+Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently
+dropped.
diff --git a/docs/talos/reference/index.md b/docs/talos/reference/index.md
index a99ce7691e..41df753a2c 100644
--- a/docs/talos/reference/index.md
+++ b/docs/talos/reference/index.md
@@ -19,3 +19,8 @@ Technical reference documentation for Ory Talos.
- [Error codes](error-codes.md) — HTTP and gRPC error codes returned by the API
- [Token format](token-format.md) — API key and session token structure
+- [Audit events](events.md) — emitted lifecycle and verification events
+
+## CLI
+
+- [`talos`](cli/talos.md) — root command and subcommand index
diff --git a/docs/talos/reference/token-format.md b/docs/talos/reference/token-format.md
index 9110855fb7..626ff6c3bf 100644
--- a/docs/talos/reference/token-format.md
+++ b/docs/talos/reference/token-format.md
@@ -23,12 +23,12 @@ prod_v1_5Z7Hn9K3mPqRtVwXyBcDeFgHiJkLmNoPqRsTuVwXyZ_AbC3XyZ789e
### Components
-| Component | Length | Description |
-| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------- |
-| `prefix` | 1-8 chars | User-defined label (e.g., `prod`, `dev`, `test`). Set via `credentials.api_keys.prefix.current` in config. |
-| `v1` | 2 chars | Format version identifier |
-| `identifier` | ~32 chars | Base58-encoded timestamp and UUID v4 |
-| `checksum` | 10-11 chars | HMAC-SHA256 truncated to 64 bits, Base58-encoded |
+| Component | Length | Description |
+| ------------ | ----------- | ----------------------------------------------------------------------------------------------------------- |
+| `prefix` | 1-16 chars | User-defined label (e.g., `prod`, `dev`, `test`). Set via `credentials.api_keys.prefix.current` in config. |
+| `v1` | 2 chars | Format version identifier |
+| `identifier` | ~64 chars | Base58-encoded `timestamp:uuid` payload |
+| `checksum` | ~44 chars | Full 32-byte HMAC-SHA256 over `prefix_v1_identifier_`, Base58-encoded |
### Identifier encoding
@@ -37,19 +37,19 @@ The identifier is a Base58 encoding of `timestamp:uuid`:
- **Timestamp**: Unix epoch seconds (int64). Embedded at key creation time.
- **UUID**: UUID v4 (36 chars with hyphens). Used as the `key_id` for database lookup.
-Base58 encoding uses the Bitcoin alphabet (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually
-ambiguous characters (`0`, `O`, `I`, `l`).
+Base58 encoding uses the Bitcoin alphabet
+(`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually ambiguous
+characters (`0`, `O`, `I`, `l`).
### Checksum verification
The checksum is computed over the payload `prefix_v1_identifier_`:
-1. Compute HMAC-SHA256 using the current HMAC secret
-2. Truncate to 64 bits
-3. Base58-encode the result
+1. Compute HMAC-SHA256 using the current HMAC secret (`secrets.hmac.current`)
+2. Base58-encode the full 32-byte digest (no truncation)
-During verification, all configured secrets (current + retired) are tried in order. This supports secret rotation without
-invalidating existing keys.
+During verification, all configured secrets (current + retired) are tried in order. This supports
+secret rotation without invalidating existing keys.
### Credential routing
@@ -64,7 +64,8 @@ When a credential is submitted for verification, Talos identifies the credential
## Imported key format
-Imported keys have no format requirements. Any string credential can be imported. Talos stores a tenant-scoped hash:
+Imported keys have no format requirements. Any string credential can be imported. Talos stores a
+tenant-scoped hash:
```
SHA-512/256(network_id + 0x00 + raw_key)
@@ -82,8 +83,25 @@ Derived tokens produced as JWTs follow the standard JWT format:
eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature
```
-Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm is determined by the `alg`
-field in the JWK (EdDSA or RS256).
+Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm
+is determined by the `alg` field in the JWK (EdDSA or RS256).
+
+#### Signing key selection (`kid` hint)
+
+The data plane resolves the active signing key on every derive request. The `kid` header in the
+issued JWT identifies which JWK from the configured JWKS produced the signature.
+
+Resolution order:
+
+1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK whose `kid`
+ matches. If no JWK has that `kid`, signing fails with `InternalError` and the requested
+ `signing_key_id` appears in the error details.
+2. Otherwise, Talos prefers the first key with `"use": "sig"`.
+3. Otherwise, Talos returns the first key in the JWKS.
+
+Set `signing_key_id` explicitly in production so rotating signing material becomes a config change
+rather than a JWKS-ordering side effect. In multi-tenant deployments the JWKS resolves per tenant
+via the contextualizer; the `kid` hint is also per-tenant.
### Macaroon
@@ -93,13 +111,13 @@ Macaroon tokens use a configurable prefix:
_v1_
```
-The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`). The data section contains the
-macaroon identifier and signature.
+The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`).
+The data section contains the macaroon identifier and signature.
## ID formats
| Context | Format | Length | Example |
| ------------------ | ----------------------- | --------- | -------------------------------------- |
| Database storage | UUID v4 string | 36 chars | `550e8400-e29b-41d4-a716-446655440000` |
-| API key identifier | Base58-encoded | ~32 chars | `5Z7Hn9K3mPqRtVwXyBcDeFg` |
+| API key identifier | Base58-encoded | ~64 chars | `5Z7Hn9K3mPqRtVwXyBcDeFgHiJkLmNoPqRsTuVwXyZ` |
| Imported key hash | Hex-encoded SHA-512/256 | 64 chars | `a1b2c3d4...` |
diff --git a/src/sidebar.ts b/src/sidebar.ts
index b191ea74b5..b62b6b2d47 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -955,7 +955,7 @@ const talos: SidebarItemsConfig = [
},
{
type: "category",
- label: "talos/integrate",
+ label: "Integrate",
collapsed: false,
link: { type: "doc", id: "talos/integrate/index" },
items: [
@@ -977,7 +977,7 @@ const talos: SidebarItemsConfig = [
},
{
type: "category",
- label: "talos/operate",
+ label: "Operate",
collapsed: false,
link: { type: "doc", id: "talos/operate/index" },
items: [
@@ -1039,7 +1039,6 @@ const talos: SidebarItemsConfig = [
"talos/concepts/credential-types",
"talos/concepts/token-format",
"talos/concepts/security-model",
- "talos/concepts/ip-restrictions",
"talos/concepts/caching",
"talos/concepts/rate-limiting",
"talos/concepts/token-derivation-security",
From 8740078595b66e7a6eea2d8d734de6cf424021a9 Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Tue, 28 Apr 2026 14:05:53 +0200
Subject: [PATCH 8/8] chore: synchronize workspaces
---
docs/talos/CLAUDE.md | 48 ++--
docs/talos/concepts/architecture.md | 81 +++---
docs/talos/concepts/caching.md | 13 +-
docs/talos/concepts/credential-types.md | 26 +-
docs/talos/concepts/index.md | 3 +-
docs/talos/concepts/ip-restrictions.md | 75 +++---
docs/talos/concepts/rate-limiting.md | 88 +++----
docs/talos/concepts/security-model.md | 124 +++++-----
.../concepts/token-derivation-security.md | 68 ++----
docs/talos/concepts/token-format.md | 7 +-
docs/talos/index.md | 44 ++--
...tch-operations.md => batch-operations.mdx} | 46 ++--
.../{derive-tokens.md => derive-tokens.mdx} | 73 +++---
.../{error-handling.md => error-handling.mdx} | 51 ++--
.../{import-keys.md => import-keys.mdx} | 47 ++--
docs/talos/integrate/index.md | 72 +++---
...ip-restrictions.md => ip-restrictions.mdx} | 57 ++---
...sue-and-verify.md => issue-and-verify.mdx} | 72 +++---
.../{key-lifecycle.md => key-lifecycle.mdx} | 73 +++---
.../{rate-limiting.md => rate-limiting.mdx} | 96 +++-----
docs/talos/integrate/sdk/curl.md | 18 +-
docs/talos/integrate/sdk/go.md | 37 ++-
...self-revocation.md => self-revocation.mdx} | 48 ++--
docs/talos/operate/benchmarks.md | 31 ++-
docs/talos/operate/cache/index.md | 8 +-
docs/talos/operate/cache/memory.md | 8 +-
docs/talos/operate/cache/redis.md | 54 ++--
docs/talos/operate/configure.md | 20 +-
docs/talos/operate/database/cockroachdb.md | 41 ++--
docs/talos/operate/database/index.md | 3 +-
docs/talos/operate/database/migrations.md | 50 ++--
docs/talos/operate/database/mysql.md | 25 +-
docs/talos/operate/database/postgresql.md | 68 +++---
docs/talos/operate/deploy/edge-proxy.md | 58 ++---
docs/talos/operate/deploy/kubernetes.md | 19 +-
docs/talos/operate/deploy/separate-planes.md | 34 +--
docs/talos/operate/index.md | 25 +-
docs/talos/operate/install.md | 3 +-
.../talos/operate/monitoring/health-checks.md | 4 +-
docs/talos/operate/monitoring/index.md | 3 +-
docs/talos/operate/monitoring/metrics.md | 8 +-
docs/talos/operate/monitoring/tracing.md | 5 +-
docs/talos/operate/multi-tenancy.md | 94 ++++---
docs/talos/operate/secrets.md | 73 +++---
docs/talos/operate/security-hardening.md | 65 +++--
docs/talos/operate/tls.md | 3 +-
docs/talos/operate/troubleshooting.md | 10 +-
...er-commercial.md => docker-commercial.mdx} | 14 +-
docs/talos/quickstart/{index.md => index.mdx} | 35 ++-
docs/talos/quickstart/preview.mdx | 52 ++--
...n-batch-import-api-keys.RequestSchema.json | 103 +++++++-
...min-batch-import-api-keys.StatusCodes.json | 186 +++++++++++++-
.../api/admin-batch-import-api-keys.api.mdx | 77 ++----
...n-batch-verify-api-keys.RequestSchema.json | 31 ++-
...min-batch-verify-api-keys.StatusCodes.json | 126 +++++++++-
.../api/admin-batch-verify-api-keys.api.mdx | 77 ++----
...delete-imported-api-key.ParamsDetails.json | 12 +-
...delete-imported-api-key.RequestSchema.json | 2 +-
...n-delete-imported-api-key.StatusCodes.json | 37 ++-
.../api/admin-delete-imported-api-key.api.mdx | 70 ++----
.../api/admin-derive-token.RequestSchema.json | 39 ++-
.../api/admin-derive-token.StatusCodes.json | 52 +++-
.../reference/api/admin-derive-token.api.mdx | 75 ++----
...in-get-imported-api-key.ParamsDetails.json | 12 +-
...in-get-imported-api-key.RequestSchema.json | 2 +-
...dmin-get-imported-api-key.StatusCodes.json | 126 +++++++++-
.../api/admin-get-imported-api-key.api.mdx | 69 ++----
...dmin-get-issued-api-key.ParamsDetails.json | 12 +-
...dmin-get-issued-api-key.RequestSchema.json | 2 +-
.../admin-get-issued-api-key.StatusCodes.json | 126 +++++++++-
.../api/admin-get-issued-api-key.api.mdx | 70 ++----
.../api/admin-get-jwks.RequestSchema.json | 2 +-
.../api/admin-get-jwks.StatusCodes.json | 43 +++-
.../reference/api/admin-get-jwks.api.mdx | 66 ++---
.../admin-import-api-key.RequestSchema.json | 92 ++++++-
.../api/admin-import-api-key.StatusCodes.json | 136 ++++++++++-
.../api/admin-import-api-key.api.mdx | 78 ++----
.../admin-issue-api-key.RequestSchema.json | 73 +++++-
.../api/admin-issue-api-key.StatusCodes.json | 140 ++++++++++-
.../reference/api/admin-issue-api-key.api.mdx | 77 ++----
...-list-imported-api-keys.ParamsDetails.json | 23 +-
...-list-imported-api-keys.RequestSchema.json | 2 +-
...in-list-imported-api-keys.StatusCodes.json | 146 ++++++++++-
.../api/admin-list-imported-api-keys.api.mdx | 70 ++----
...in-list-issued-api-keys.ParamsDetails.json | 23 +-
...in-list-issued-api-keys.RequestSchema.json | 2 +-
...dmin-list-issued-api-keys.StatusCodes.json | 142 ++++++++++-
.../api/admin-list-issued-api-keys.api.mdx | 71 ++----
.../admin-revoke-api-key.ParamsDetails.json | 12 +-
.../admin-revoke-api-key.RequestSchema.json | 35 ++-
.../api/admin-revoke-api-key.StatusCodes.json | 37 ++-
.../api/admin-revoke-api-key.api.mdx | 74 ++----
...n-rotate-issued-api-key.ParamsDetails.json | 12 +-
...n-rotate-issued-api-key.RequestSchema.json | 78 +++++-
...min-rotate-issued-api-key.StatusCodes.json | 230 +++++++++++++++++-
.../api/admin-rotate-issued-api-key.api.mdx | 81 ++----
...update-imported-api-key.ParamsDetails.json | 12 +-
...update-imported-api-key.RequestSchema.json | 57 ++++-
...n-update-imported-api-key.StatusCodes.json | 126 +++++++++-
.../api/admin-update-imported-api-key.api.mdx | 73 ++----
...n-update-issued-api-key.ParamsDetails.json | 12 +-
...n-update-issued-api-key.RequestSchema.json | 54 +++-
...min-update-issued-api-key.StatusCodes.json | 126 +++++++++-
.../api/admin-update-issued-api-key.api.mdx | 74 ++----
.../admin-verify-api-key.RequestSchema.json | 22 +-
.../api/admin-verify-api-key.StatusCodes.json | 114 ++++++++-
.../api/admin-verify-api-key.api.mdx | 81 ++----
.../reference/api/ory-talos-api.info.mdx | 34 +--
.../api/revoke-api-key.RequestSchema.json | 37 ++-
.../api/revoke-api-key.StatusCodes.json | 41 +++-
.../reference/api/revoke-api-key.api.mdx | 79 ++----
docs/talos/reference/api/sidebar.ts | 6 +-
.../reference/cli/talos-jwk-generate-ecdsa.md | 9 +-
.../reference/cli/talos-jwk-generate-eddsa.md | 7 +-
.../reference/cli/talos-jwk-generate-hmac.md | 9 +-
.../reference/cli/talos-jwk-generate-rsa.md | 7 +-
.../talos/reference/cli/talos-jwk-generate.md | 12 +-
docs/talos/reference/cli/talos-jwk-get.md | 13 +-
docs/talos/reference/cli/talos-jwk.md | 12 +-
.../reference/cli/talos-keys-batch-verify.md | 4 +-
.../reference/cli/talos-keys-derive-token.md | 4 +-
.../cli/talos-keys-imported-batch-import.md | 4 +-
.../cli/talos-keys-imported-delete.md | 4 +-
.../reference/cli/talos-keys-imported-get.md | 4 +-
.../cli/talos-keys-imported-import.md | 4 +-
.../reference/cli/talos-keys-imported-list.md | 4 +-
.../cli/talos-keys-imported-revoke.md | 4 +-
.../reference/cli/talos-keys-imported.md | 16 +-
docs/talos/reference/cli/talos-keys-issue.md | 4 +-
.../reference/cli/talos-keys-issued-get.md | 4 +-
.../reference/cli/talos-keys-issued-issue.md | 4 +-
.../reference/cli/talos-keys-issued-list.md | 4 +-
.../reference/cli/talos-keys-issued-rotate.md | 4 +-
.../reference/cli/talos-keys-issued-update.md | 4 +-
docs/talos/reference/cli/talos-keys-issued.md | 14 +-
docs/talos/reference/cli/talos-keys-revoke.md | 4 +-
.../reference/cli/talos-keys-self-revoke.md | 4 +-
docs/talos/reference/cli/talos-keys-verify.md | 4 +-
docs/talos/reference/cli/talos-keys.md | 20 +-
.../talos/reference/cli/talos-migrate-down.md | 7 +-
.../reference/cli/talos-migrate-force.md | 14 +-
.../reference/cli/talos-migrate-status.md | 11 +-
docs/talos/reference/cli/talos-migrate-up.md | 9 +-
docs/talos/reference/cli/talos-migrate.md | 12 +-
docs/talos/reference/cli/talos-proxy.md | 12 +-
docs/talos/reference/cli/talos-serve-admin.md | 9 +-
docs/talos/reference/cli/talos-serve-check.md | 8 +-
docs/talos/reference/cli/talos-serve.md | 9 +-
docs/talos/reference/cli/talos.md | 20 +-
.../talos/reference/{config.md => config.mdx} | 14 +-
docs/talos/reference/error-codes.md | 8 +-
docs/talos/reference/events.md | 17 +-
docs/talos/reference/index.md | 2 +-
docs/talos/reference/token-format.md | 54 ++--
154 files changed, 4064 insertions(+), 2408 deletions(-)
rename docs/talos/integrate/{batch-operations.md => batch-operations.mdx} (72%)
rename docs/talos/integrate/{derive-tokens.md => derive-tokens.mdx} (70%)
rename docs/talos/integrate/{error-handling.md => error-handling.mdx} (70%)
rename docs/talos/integrate/{import-keys.md => import-keys.mdx} (76%)
rename docs/talos/integrate/{ip-restrictions.md => ip-restrictions.mdx} (77%)
rename docs/talos/integrate/{issue-and-verify.md => issue-and-verify.mdx} (64%)
rename docs/talos/integrate/{key-lifecycle.md => key-lifecycle.mdx} (67%)
rename docs/talos/integrate/{rate-limiting.md => rate-limiting.mdx} (61%)
rename docs/talos/integrate/{self-revocation.md => self-revocation.mdx} (70%)
rename docs/talos/quickstart/{docker-commercial.md => docker-commercial.mdx} (84%)
rename docs/talos/quickstart/{index.md => index.mdx} (82%)
rename docs/talos/reference/{config.md => config.mdx} (98%)
diff --git a/docs/talos/CLAUDE.md b/docs/talos/CLAUDE.md
index 3f89f4321f..5d6fd88460 100644
--- a/docs/talos/CLAUDE.md
+++ b/docs/talos/CLAUDE.md
@@ -5,31 +5,42 @@
Use `jq` instead of `python3` for all JSON operations in code examples:
- **Pretty-print:** `| jq .` not `| python3 -m json.tool`
-- **Extract fields:** `| jq -r '.field'` not
- `| python3 -c "import json,sys; print(json.load(sys.stdin)['field'])"`
+- **Extract required fields:** `| jq -er '.field'` (the `-e` flag exits non-zero on `null` so `set -e` aborts the snippet instead
+ of silently exporting an empty value).
+- **Extract optional fields:** `| jq -r '.field'` is fine when the field may legitimately be missing.
-**Never write curl output to temporary files.** Capture responses in shell variables instead.
-File-based operations fail when `/tmp` doesn't exist or isn't writable.
+**Never write curl output to temporary files.** Capture responses in shell variables instead. File-based operations fail when
+`/tmp` doesn't exist or isn't writable.
+
+## Passing state between doctest blocks
+
+Doctest runs each code block in a fresh `bash -eu -o pipefail` subprocess and auto-captures the exported environment after each
+successful block. To make a value available to the next block, just `export` it — no manual write to `$DOCTEST_ENV_FILE` is
+needed.
```bash
-# Good: variable-based
+# Good: variable-based, exported for the next block, asserts the field is present
RESPONSE=$(curl -s -X POST "$URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name": "my-key"}')
echo "$RESPONSE" | jq .
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')
# Bad: file-based
curl -s ... -o /tmp/response.json
jq . /tmp/response.json
KEY_ID=$(jq -r '.key_id' /tmp/response.json)
rm -f /tmp/response.json
+
+# Bad: redirecting to $DOCTEST_ENV_FILE (legacy; auto-capture handles this now)
+KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
+echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
```
## API Field Documentation
-Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or
-enum tables. These are maintained in the canonical references:
+Integration guides under `integrate/` must NOT duplicate API field tables, error code tables, or enum tables. These are maintained
+in the canonical references:
- **Field tables** -> auto-generated API reference at `reference/api/*.api.mdx`
- **Error codes** -> `reference/error-codes.md`
@@ -37,10 +48,9 @@ enum tables. These are maintained in the canonical references:
### What belongs in integration guides
- **Workflow and examples**: curl commands, step-by-step instructions, the "how" and "why"
-- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The
- response includes a `secret` field -- store it securely")
-- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT
- vs macaroon)
+- **Brief inline mentions**: 1-3 sentences highlighting the most important fields (e.g., "The response includes a `secret` field
+ -- store it securely")
+- **Conceptual comparisons**: tables comparing patterns, trade-offs, or usage scenarios (e.g., JWT vs macaroon)
- **Operational constraints**: limits, cache control headers, retry strategies
- **Links to reference**: always link to the canonical source for complete field/error details
@@ -53,9 +63,8 @@ enum tables. These are maintained in the canonical references:
### Link format
-**All links MUST be relative links to markdown/mdx files with the file extension.** Never use
-absolute links (starting with `/`) or links without a file extension. Hashbang anchors are allowed
-after the file extension.
+**All links MUST be relative links to markdown/mdx files with the file extension.** Never use absolute links (starting with `/`)
+or links without a file extension. Hashbang anchors are allowed after the file extension.
- Links to `.md` files: `[text](../reference/error-codes.md#section)`
- Links to `.api.mdx` files: `[text](../reference/api/admin-issue-api-key.api.mdx)`
@@ -88,13 +97,11 @@ Ensure that notes / callouts have two line breaks, or they will get formatted in
**Incorrect:**
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by
-external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
```
```md
-:::note Internal package The Go client is in an `internal/` package and cannot be imported by
-external Go modules. :::
+:::note Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules. :::
```
Correct:
@@ -102,8 +109,7 @@ Correct:
```md
:::note
-Internal package The Go client is in an `internal/` package and cannot be imported by external Go
-modules.
+Internal package The Go client is in an `internal/` package and cannot be imported by external Go modules.
:::
```
diff --git a/docs/talos/concepts/architecture.md b/docs/talos/concepts/architecture.md
index b0ba17fa0c..35ace68a1d 100644
--- a/docs/talos/concepts/architecture.md
+++ b/docs/talos/concepts/architecture.md
@@ -8,24 +8,28 @@ Talos separates API key management into two planes.
## Admin plane
-The admin plane handles all write operations: key issuance, rotation, revocation, token derivation,
-and JWKS. It is typically exposed only to internal services.
+The admin plane handles all key management and verification operations: key issuance, rotation, revocation, token derivation,
+JWKS, and verification (single and batch). It is exposed only to internal services and clients with admin credentials.
-Endpoints: `/v2alpha1/admin/`
+Endpoints: `/v2alpha1/admin/`, including `/v2alpha1/admin/apiKeys:verify` and `/v2alpha1/admin/apiKeys:batchVerify`.
+
+For low-latency verification close to clients, deploy the commercial [edge proxy](../operate/deploy/edge-proxy.md) as a sidecar.
+The proxy caches admin verify responses locally, so applications get sub-millisecond cache hits without exposing the admin plane
+publicly.
## Data plane
-The data plane handles high-throughput read operations: key verification, batch verification, and
-self-revocation. It is designed for low-latency edge deployment.
+The data plane handles self-service operations that credential holders perform with proof of possession of the credential itself,
+no admin authentication required.
-Endpoints: `/v2alpha1/admin/apiKeys:verify`, `/v2alpha1/admin/apiKeys:batchVerify`, `/v2alpha1/apiKeys:selfRevoke`
+Endpoints: `POST /v2alpha1/apiKeys:selfRevoke`
-## Request flow
+## Verification flow
```
-Client --> Data Plane --> Cache (hit?) --> Database --> Response
- | ^
- +-- cache hit ---------------+
+Client --> Verifier --> Cache (hit?) --> Database --> Response
+ | ^
+ +-- cache hit ---------------+
```
1. Client sends credential to `POST /v2alpha1/admin/apiKeys:verify`
@@ -37,14 +41,13 @@ Client --> Data Plane --> Cache (hit?) --> Database --> Response
## Deployment topologies
-| Topology | Edition | Description |
-| ------------ | ---------- | --------------------------------------------- |
-| Single-node | OSS | One process serves both planes |
-| Split planes | Commercial | Admin and data planes as separate deployments |
-| Edge proxy | Commercial | Data plane at the edge with local cache |
+| Topology | Edition | Description |
+| ------------ | ---------- | -------------------------------------------------------------------- |
+| Single-node | OSS | One process serves both planes |
+| Split planes | Commercial | Admin and data planes as separate deployments |
+| Edge proxy | Commercial | Sidecar proxy at the edge that caches admin verify responses locally |
-Both planes share the same database. The data plane can use caching (memory or Redis) to minimize
-database load.
+Both planes share the same database. Verification uses caching (memory or Redis) to minimize database load.
## Ports
@@ -64,9 +67,8 @@ The system is divided into distinct layers:
- **Persistence layer**: Database abstraction with pluggable drivers
- **Cache layer**: Performance optimization with multiple backends
-This separation allows independent scaling of components, different SLOs for different operations
-(admin targets \<100ms p99, data plane targets \<3ms p99), and clear boundaries between
-responsibilities.
+This separation allows independent scaling of components, different SLOs for different operations (admin targets \<100ms p99, data
+plane targets \<3ms p99), and clear boundaries between responsibilities.
### Production-first design
@@ -78,8 +80,8 @@ responsibilities.
### Performance characteristics
- Self-contained tokens (JWT/macaroon) enable stateless verification
-- HMAC-SHA256 keeps the revocation check on the order of microseconds; bcrypt
- would cap a single core at roughly 10 verifications per second
+- HMAC-SHA256 keeps the revocation check on the order of microseconds; bcrypt would cap a single core at roughly 10 verifications
+ per second
- LRU caching for hot paths
- Minimal allocations in the verification path
@@ -126,21 +128,21 @@ Clients (CLI, SDK, HTTP)
+-----------+ +-----------+
```
-All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through
-middleware for logging, metrics, and tracing before being routed to the appropriate plane.
+All requests enter through a single HTTP server built on grpc-gateway (port 4420) and pass through middleware for logging,
+metrics, and tracing before being routed to the appropriate plane.
## Component overview
### HTTP server
-The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both
-planes through a single port, handles CORS and compression, and exposes OpenAPI documentation.
+The API layer uses grpc-gateway for HTTP/JSON routing with protobuf-based schemas. It serves both planes through a single port,
+handles CORS and compression, and exposes OpenAPI documentation.
### Service layer
-Business logic is split between the admin plane service (key lifecycle, import, token derivation,
-input validation) and the data plane verifier (token parsing, signature verification, revocation
-checking, cache management). The verifier is optimized for the hot path with minimal allocations.
+Business logic is split between the admin plane service (key lifecycle, import, token derivation, input validation) and the data
+plane verifier (token parsing, signature verification, revocation checking, cache management). The verifier is optimized for the
+hot path with minimal allocations.
### Persistence
@@ -171,25 +173,22 @@ Talos supports multiple JWT signing algorithms and a separate API key hashing me
- **API key hashing**
- `HMAC-SHA256` -- used for API key revocation checks (\<1ms with constant-time comparison)
-The JWT signing algorithm is determined per JWK by its `alg` field, so one JWKS can contain keys for
-multiple signing algorithms at the same time.
+The JWT signing algorithm is determined per JWK by its `alg` field, so one JWKS can contain keys for multiple signing algorithms
+at the same time.
### Observability
Built-in instrumentation across three pillars:
-- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate
- counters
-- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and
- Jaeger exporters
+- **Metrics** -- Prometheus exposition on port 4422 with request latency histograms and error rate counters
+- **Tracing** -- OpenTelemetry with W3C Trace Context propagation, configurable sampling, OTLP and Jaeger exporters
- **Logging** -- structured JSON logging via slog with correlation IDs and contextual fields
## Scalability
### Small (\<1k RPS)
-A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external
-dependencies required.
+A single Talos instance handles both planes with SQLite and an in-memory LRU cache. No external dependencies required.
- OSS edition sufficient
- 1 CPU, 512MB RAM
@@ -197,8 +196,8 @@ dependencies required.
### Medium (10-50k RPS)
-Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for
-durability. Redis provides shared caching across data plane instances.
+Separate admin and data plane deployments behind a load balancer. PostgreSQL replaces SQLite for durability. Redis provides shared
+caching across data plane instances.
- Commercial edition
- Auto-scaling for data plane
@@ -206,8 +205,8 @@ durability. Redis provides shared caching across data plane instances.
### Large (200k+ RPS)
-A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis
-cache and PostgreSQL with read replicas and connection pooling. Supports multi-region deployment.
+A cluster of 10-50+ stateless data plane instances with auto-scaling, backed by a distributed Redis cache and PostgreSQL with read
+replicas and connection pooling. Supports multi-region deployment.
- Commercial edition
- Regional data plane deployment
diff --git a/docs/talos/concepts/caching.md b/docs/talos/concepts/caching.md
index 81d02e7382..8fb4f9e165 100644
--- a/docs/talos/concepts/caching.md
+++ b/docs/talos/concepts/caching.md
@@ -4,14 +4,13 @@ title: Caching and consistency
# Caching and consistency
-Talos caches verification results to reduce database load and improve latency. The OSS edition
-ships a no-op cache; in-memory and Redis backends are commercial-only — see
-[Caching](../operate/cache/index.md) for backend selection.
+Talos caches verification results to reduce database load and improve latency. The OSS edition ships a no-op cache; in-memory and
+Redis backends are commercial-only — see [Caching](../operate/cache/index.md) for backend selection.
## How it works
-When caching is enabled, the first verification request for a key hits the database. Subsequent
-requests within the cache TTL are served from cache without a database lookup.
+When caching is enabled, the first verification request for a key hits the database. Subsequent requests within the cache TTL are
+served from cache without a database lookup.
## Cache types
@@ -40,8 +39,8 @@ curl -X POST http://localhost:4420/v2alpha1/admin/apiKeys:verify \
-d '{"credential": "..."}'
```
-See the [quickstart revocation check](../quickstart/index.md) and the
-[curl SDK reference](../integrate/sdk/curl.md) for tested examples using cache bypass.
+See the [quickstart revocation check](../quickstart/index.mdx) and the [curl SDK reference](../integrate/sdk/curl.md) for tested
+examples using cache bypass.
## TTL guidelines
diff --git a/docs/talos/concepts/credential-types.md b/docs/talos/concepts/credential-types.md
index eb3eec8a95..38e45d8808 100644
--- a/docs/talos/concepts/credential-types.md
+++ b/docs/talos/concepts/credential-types.md
@@ -8,35 +8,31 @@ Talos manages four credential types.
## Issued API keys
-Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable
-TTL. The key ID (UUID) is embedded in the token for direct database lookup. The full secret is
-returned once at creation.
+Generated by Talos with the format `prefix_v1_identifier_checksum`. Long-lived with configurable TTL. The key ID (UUID) is
+embedded in the token for direct database lookup. The full secret is returned once at creation.
**Lifecycle**: Issue, rotate, update metadata, revoke.
## Imported API keys
External credentials (Stripe, GitHub, etc.) stored by hash. Any string format accepted. Talos stores
-`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and
-scopes as issued keys.
+`SHA-512/256(network_id + 0x00 + raw_key)` and never the raw key. Supports the same metadata and scopes as issued keys.
**Lifecycle**: Import, update metadata, revoke, delete.
## Derived JWTs
-Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg`
-field in the JWK (EdDSA or RS256). Can be verified independently using the JWKS endpoint
-(`GET /v2alpha1/admin/derivedKeys/jwks.json`). Claims include `key_id`, `actor_id`, scopes, and
-expiration.
+Short-lived tokens derived from a parent API key. The signing algorithm is determined by the `alg` field in the JWK (EdDSA or
+RS256). Can be verified independently using the JWKS endpoint (`GET /v2alpha1/admin/derivedKeys/jwks.json`). Claims include
+`key_id`, `actor_id`, scopes, and expiration.
## Derived macaroons
-Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and
-contextual attenuation.
+Short-lived tokens with HMAC binding. Format: `prefix_v1_base64data`. Support scope restriction and contextual attenuation.
## Credential routing
-When a credential is submitted to `/v2alpha1/admin/apiKeys:verify`, Talos identifies the type
-automatically by its format and routes it to the appropriate verification handler. See the
-[credential routing table](../reference/token-format.md#credential-routing) for the full
-format-to-type mapping and lookup methods.
+When a credential is submitted to `/v2alpha1/admin/apiKeys:verify`, Talos identifies the type automatically by its format and
+routes it to the appropriate verification handler. See the
+[credential routing table](../reference/token-format.md#credential-routing) for the full format-to-type mapping and lookup
+methods.
diff --git a/docs/talos/concepts/index.md b/docs/talos/concepts/index.md
index 6b57a7b962..6ae6bef95b 100644
--- a/docs/talos/concepts/index.md
+++ b/docs/talos/concepts/index.md
@@ -11,7 +11,6 @@ Core ideas behind Ory Talos.
- [Token format](token-format.md) — v1 key format specification
- [Security model](security-model.md) — cryptographic primitives and tenant isolation
- [Caching and consistency](caching.md) — verification caching and revocation propagation
-- [Token derivation security](token-derivation-security.md) — stateless verification and revocation
- semantics
+- [Token derivation security](token-derivation-security.md) — stateless verification and revocation semantics
- [Rate limiting](rate-limiting.md) — rate limit metadata on API keys
- [IP restrictions](ip-restrictions.md) — CIDR-based access control for API keys
diff --git a/docs/talos/concepts/ip-restrictions.md b/docs/talos/concepts/ip-restrictions.md
index 6278eaf2a7..aa67aaf7b4 100644
--- a/docs/talos/concepts/ip-restrictions.md
+++ b/docs/talos/concepts/ip-restrictions.md
@@ -5,10 +5,9 @@ description: CIDR-based allowlists that restrict which client IPs can use an API
# IP restrictions
-Talos supports per-key IP restrictions that limit which client IP addresses can use an API key.
-Restrictions are defined as a list of CIDR ranges (for example, `192.168.1.0/24` or
-`2001:db8::/32`). Only requests originating from an IP within the allowlist are accepted. Keys
-without IP restrictions accept traffic from any address.
+Talos supports per-key IP restrictions that limit which client IP addresses can use an API key. Restrictions are defined as a list
+of CIDR ranges (for example, `192.168.1.0/24` or `2001:db8::/32`). Only requests originating from an IP within the allowlist are
+accepted. Keys without IP restrictions accept traffic from any address.
## How IP restrictions work
@@ -16,9 +15,9 @@ IP restriction enforcement has two stages: **IP resolution** and **CIDR matching
### IP resolution
-When a verification request arrives, Talos captures all IP-related headers from the HTTP request
-into context through middleware. At verification time, the configured **client IP source**
-determines which header to use for extracting the client address. The available sources are:
+When a verification request arrives, Talos captures all IP-related headers from the HTTP request into context through middleware.
+At verification time, the configured **client IP source** determines which header to use for extracting the client address. The
+available sources are:
| Source | Header / value used | Typical use case |
| ------------------ | ---------------------------- | -------------------------------------- |
@@ -28,33 +27,32 @@ determines which header to use for extracting the client address. The available
| `X_REAL_IP` | `X-Real-Ip` | Behind NGINX with `proxy_set_header` |
| `TRUE_CLIENT_IP` | `True-Client-Ip` | Behind Akamai or Cloudflare Enterprise |
-If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is
-set once at startup and applies to all verification requests.
+If the selected header is empty, Talos falls back to the TCP remote address. The client IP source is set once at startup and
+applies to all verification requests.
### CIDR matching
-After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP
-falls within any of the ranges. Both IPv4 and IPv6 CIDR notation are supported (for example,
-`10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32` (IPv4) or `/128` (IPv6) range.
+After resolving the client IP, Talos parses the key's allowed CIDR list and checks whether the IP falls within any of the ranges.
+Both IPv4 and IPv6 CIDR notation are supported (for example, `10.0.0.0/8` and `fd00::/8`). A single IP can be expressed as a `/32`
+(IPv4) or `/128` (IPv6) range.
-If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification
-fails with error code `VERIFICATION_ERROR_IP_NOT_ALLOWED`.
+If the IP matches at least one CIDR range, verification proceeds. If no range matches, verification fails with error code
+`VERIFICATION_ERROR_IP_NOT_ALLOWED`.
## Fail-closed behavior
-IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for
-example, because the request context does not contain IP metadata -- the verification request is
-denied. This prevents accidental access when header forwarding is misconfigured.
+IP restrictions use a **fail-closed** design. If Talos cannot determine the client IP -- for example, because the request context
+does not contain IP metadata -- the verification request is denied. This prevents accidental access when header forwarding is
+misconfigured.
-This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking
-legitimate traffic during limiter outages.
+This is the opposite of [rate limiting](rate-limiting.md), which fails open to avoid blocking legitimate traffic during limiter
+outages.
## Cache interaction
-Cached verification results still contain the key's allowed CIDR list. When a cached key is
-returned, Talos re-evaluates the IP restriction against the **current request's** client IP before
-returning a success response. This means IP restrictions are enforced on every request, regardless
-of whether the result came from cache or the database.
+Cached verification results still contain the key's allowed CIDR list. When a cached key is returned, Talos re-evaluates the IP
+restriction against the **current request's** client IP before returning a success response. This means IP restrictions are
+enforced on every request, regardless of whether the result came from cache or the database.
The enforcement sequence is:
@@ -66,29 +64,24 @@ The enforcement sequence is:
## IPv4 and IPv6 support
-IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same
-allowlist. Talos parses client addresses using Go's `net.ParseIP`, which handles both formats
-transparently. There is no implicit mapping between IPv4 and IPv6 -- a `10.0.0.0/8` range does not
-match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
+IP restrictions support both address families. You can mix IPv4 and IPv6 CIDR ranges in the same allowlist. Talos parses client
+addresses using Go's `net.ParseIP`, which handles both formats transparently. There is no implicit mapping between IPv4 and IPv6
+-- a `10.0.0.0/8` range does not match the IPv4-mapped IPv6 address `::ffff:10.0.0.1`.
## Key concepts
-- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is
- denied. Keys without restrictions accept all IPs.
+- **Allowlist model** -- IP restrictions define which IPs are permitted. Any IP not in the list is denied. Keys without
+ restrictions accept all IPs.
- **Per-key granularity** -- each key has its own CIDR list. Keys do not share IP restrictions.
-- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured
- proxies cannot bypass restrictions.
-- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32`
- (IPv4) or `/128` (IPv6).
-- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside
- the key's allowed ranges. See the
- [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is
- served from cache.
+- **Fail-closed** -- if the client IP cannot be resolved, the request is denied. Misconfigured proxies cannot bypass restrictions.
+- **CIDR notation** -- ranges use standard CIDR format (`ip/prefix_length`). Single IPs use `/32` (IPv4) or `/128` (IPv6).
+- **`VERIFICATION_ERROR_IP_NOT_ALLOWED`** -- the error code returned when a request IP is outside the key's allowed ranges. See
+ the [error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
+- **Cache-safe** -- IP restrictions are enforced on every verification request, even when the key is served from cache.
## Next steps
- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
-- [Configuration reference](../reference/config.md) -- client IP source and related settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
- error codes including `VERIFICATION_ERROR_IP_NOT_ALLOWED`
+- [Configuration reference](../reference/config.mdx) -- client IP source and related settings
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
+ `VERIFICATION_ERROR_IP_NOT_ALLOWED`
diff --git a/docs/talos/concepts/rate-limiting.md b/docs/talos/concepts/rate-limiting.md
index 76ce2a560a..f81f4018e2 100644
--- a/docs/talos/concepts/rate-limiting.md
+++ b/docs/talos/concepts/rate-limiting.md
@@ -1,38 +1,33 @@
---
title: Rate limiting
-description:
- Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
+description: Per-key rate limit policies with metadata-only (OSS) or server-side enforcement (Commercial)
---
# Rate limiting
-Talos supports per-key rate limit policies that control how many requests a key can make within a
-time window. A rate limit policy consists of two fields: a **quota** (maximum request count) and a
-**window** (time period in seconds). Keys without a policy are never rate limited.
+Talos supports per-key rate limit policies that control how many requests a key can make within a time window. A rate limit policy
+consists of two fields: a **quota** (maximum request count) and a **window** (time period in seconds). Keys without a policy are
+never rate limited.
How enforcement works depends on your edition.
## OSS edition: metadata and headers
-In the OSS edition, Talos stores rate limit policies on keys and returns them in verification
-responses. It does not enforce limits itself. Your API gateway or reverse proxy reads the policy
-from the response headers and applies enforcement externally.
+In the OSS edition, Talos stores rate limit policies on keys and returns them in verification responses. It does not enforce
+limits itself. Your API gateway or reverse proxy reads the policy from the response headers and applies enforcement externally.
-This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy,
-NGINX, Kong, or a dedicated service). Verification responses include IETF-format headers that
-gateways can consume directly:
+This keeps Talos stateless while letting you use purpose-built rate limiting infrastructure (Envoy, NGINX, Kong, or a dedicated
+service). Verification responses include IETF-format headers that gateways can consume directly:
- **`RateLimit-Policy`** -- declares the key's quota and window (e.g., `"default";q=100;w=60`).
- **`RateLimit`** -- reports remaining quota (e.g., `"default";r=42`).
## Commercial edition: server-side enforcement
-The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the
-verification response returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`.
-The HTTP status remains **200** because the verification endpoint always returns a structured
-response — the rate limit status is conveyed through the response body, not the HTTP status code.
-This design allows gateways to distinguish transport errors from application-level rate limiting
-decisions.
+The commercial edition enforces rate limits inside Talos. When a key exceeds its quota, the verification response returns
+`is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`. The HTTP status remains **200** because the verification
+endpoint always returns a structured response — the rate limit status is conveyed through the response body, not the HTTP status
+code. This design allows gateways to distinguish transport errors from application-level rate limiting decisions.
### Backends
@@ -43,15 +38,15 @@ The commercial edition supports two enforcement backends:
| `memory` | GCRA | Single process (not shared) | Lost on restart |
| `redis` | GCRA | Shared across all connected pods | Survives restarts |
-Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate
-limiting without the boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp
-per key and allows requests as long as the average rate stays within the configured quota.
+Both backends use the GCRA (Generic Cell Rate Algorithm), which provides smooth, sliding-window rate limiting without the
+boundary-burst problem of fixed-window counters. GCRA tracks a single timestamp per key and allows requests as long as the average
+rate stays within the configured quota.
-**Memory** is suited for single-node deployments or development. Each process maintains independent
-counters per key, so state is not shared across pods.
+**Memory** is suited for single-node deployments or development. Each process maintains independent counters per key, so state is
+not shared across pods.
-**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the
-same Redis instance. State survives process restarts as long as Redis is available.
+**Redis** uses an atomic Lua script to maintain GCRA state shared across all pods connected to the same Redis instance. State
+survives process restarts as long as Redis is available.
### Configuration
@@ -61,16 +56,14 @@ rate_limit:
backend: memory # Requires restart: changes the backend type
```
-- **`rate_limit.enabled`** is checked on every verification request through the config provider. You
- can toggle it at runtime by editing the config file -- Talos picks up the change automatically.
-- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this
- value requires a restart because it initializes different infrastructure (in-memory maps vs. Redis
- connections).
+- **`rate_limit.enabled`** is checked on every verification request through the config provider. You can toggle it at runtime by
+ editing the config file -- Talos picks up the change automatically.
+- **`rate_limit.backend`** selects the enforcement backend (`memory` or `redis`). Changing this value requires a restart because
+ it initializes different infrastructure (in-memory maps vs. Redis connections).
## HTTP response headers
-When a key has a rate limit policy, verification responses include IETF draft-compliant headers
-regardless of edition:
+When a key has a rate limit policy, verification responses include IETF draft-compliant headers regardless of edition:
| Header | Description | Example |
| ------------------ | --------------------------------------------------- | ---------------------- |
@@ -78,32 +71,29 @@ regardless of edition:
| `RateLimit` | Reports remaining quota | `"default";r=42` |
| `Retry-After` | Seconds to wait before retrying (only when limited) | `18` |
-Gateways and clients can use these headers for both external enforcement (OSS) and client-side
-backoff (Commercial).
+Gateways and clients can use these headers for both external enforcement (OSS) and client-side backoff (Commercial).
## Fail-open behavior
-If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos
-**fails open**: verification succeeds but rate limit metadata is omitted from the response. This
-design prevents limiter outages from blocking legitimate traffic.
+If the rate limiter encounters an error (for example, Redis is temporarily unavailable), Talos **fails open**: verification
+succeeds but rate limit metadata is omitted from the response. This design prevents limiter outages from blocking legitimate
+traffic.
## Key concepts
- **Per-key isolation** -- each key has its own counter. Keys do not share rate limit budgets.
-- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g.
- `"60s"`). Both must be set for enforcement to apply.
-- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate
- limiting.
-- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota
- (Commercial only). See the
+- **Policy fields** -- `quota` (integer, maximum requests) and `window` (duration string, e.g. `"60s"`). Both must be set for
+ enforcement to apply.
+- **No policy = no limit** -- keys without a `rate_limit_policy` field are never subject to rate limiting.
+- **`VERIFICATION_ERROR_RATE_LIMITED`** -- the error code returned when a key exceeds its quota (Commercial only). See the
[error codes reference](../reference/error-codes.md#verification-error-codes) for the full list.
-- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification
- result that is still valid will be returned without consulting the rate limiter.
+- **Cache interaction** -- rate limit checks happen after cache resolution. A cached verification result that is still valid will
+ be returned without consulting the rate limiter.
## Next steps
-- [Rate limiting integration guide](../integrate/rate-limiting.md) -- attach policies, verify
- rate-limited keys, and handle quota exhaustion
-- [Configuration reference](../reference/config.md) -- all `rate_limit.*` settings
-- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification
- error codes including `VERIFICATION_ERROR_RATE_LIMITED`
+- [Rate limiting integration guide](../integrate/rate-limiting.mdx) -- attach policies, verify rate-limited keys, and handle quota
+ exhaustion
+- [Configuration reference](../reference/config.mdx) -- all `rate_limit.*` settings
+- [Error codes reference](../reference/error-codes.md#verification-error-codes) -- verification error codes including
+ `VERIFICATION_ERROR_RATE_LIMITED`
diff --git a/docs/talos/concepts/security-model.md b/docs/talos/concepts/security-model.md
index d491f65c87..b3cda1d9bb 100644
--- a/docs/talos/concepts/security-model.md
+++ b/docs/talos/concepts/security-model.md
@@ -6,45 +6,40 @@ title: Security model
## Cryptographic primitives
-| Purpose | Algorithm | Keyed by |
-| ----------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
-| API key checksum | HMAC-SHA256 (full 32-byte digest, base58-encoded) | `secrets.hmac.current` |
-| Imported key hashing | SHA-512/256 over `nid \|\| 0x00 \|\| raw_key` | Tenant `nid` (no shared secret) |
-| Macaroon root-key derivation | HMAC-SHA256 with domain `"talos/macaroon/v1/root-key"` | `secrets.hmac.current` |
-| Macaroon caveat binding | HMAC-SHA256 (libmacaroons V2) | Derived macaroon root key |
-| JWT signing | EdDSA (Ed25519) or RS256, determined by JWK `alg` | JWKS at `credentials.derived_tokens.jwt.jwks.urls` |
-| Pagination-token encryption | NaCl secretbox (XSalsa20-Poly1305) keyed by SHA-256(secret) | `secrets.pagination.current` (falls back to `secrets.default.current`) |
-
-`secrets.hmac.current` is shared between the API key checksum and the macaroon root key. Rotating
-it rotates both at once; verification falls back through `secrets.hmac.retired` for both purposes.
-Pagination secrets are completely independent from `secrets.hmac.*`. See
-[Secret management](../operate/secrets.md).
+| Purpose | Algorithm | Keyed by |
+| ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
+| API key checksum | HMAC-SHA256 (full 32-byte digest, base58-encoded) | `secrets.hmac.current` |
+| Imported key hashing | SHA-512/256 over `nid \|\| 0x00 \|\| raw_key` | Tenant `nid` (no shared secret) |
+| Macaroon root-key derivation | HMAC-SHA256 with domain `"talos/macaroon/v1/root-key"` | `secrets.hmac.current` |
+| Macaroon caveat binding | HMAC-SHA256 (libmacaroons V2) | Derived macaroon root key |
+| JWT signing | EdDSA (Ed25519) or RS256, determined by JWK `alg` | JWKS at `credentials.derived_tokens.jwt.jwks.urls` |
+| Pagination-token encryption | NaCl secretbox (XSalsa20-Poly1305) keyed by SHA-256(secret) | `secrets.pagination.current` (falls back to `secrets.default.current`) |
+
+`secrets.hmac.current` is shared between the API key checksum and the macaroon root key. Rotating it rotates both at once;
+verification falls back through `secrets.hmac.retired` for both purposes. Pagination secrets are completely independent from
+`secrets.hmac.*`. See [Secret management](../operate/secrets.md).
## JWT signing key selection
The data plane resolves the active signing key on every derive request:
-1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK with the
- matching `kid`. If no JWK in the configured JWKS has that `kid`, signing fails with
- `InternalError` and `signing_key_id` is included in the error details.
+1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK with the matching `kid`. If no JWK in the
+ configured JWKS has that `kid`, signing fails with `InternalError` and `signing_key_id` is included in the error details.
2. Otherwise, Talos prefers the first key with `"use": "sig"`.
3. Otherwise, Talos returns the first key in the JWKS.
-Set `signing_key_id` explicitly in production so rotation becomes a config change rather than a
-JWKS-ordering side effect. Multi-tenant deployments resolve the JWKS per tenant via the
-contextualizer; the `kid` hint is also per-tenant.
+Set `signing_key_id` explicitly in production so rotation becomes a config change rather than a JWKS-ordering side effect.
+Multi-tenant deployments resolve the JWKS per tenant via the contextualizer; the `kid` hint is also per-tenant.
## Secret rotation
-Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the
-old one to `retired`. During verification, all secrets in the same family are tried in order.
+Talos supports zero-downtime secret rotation. Configure the new secret as `current` and move the old one to `retired`. During
+verification, all secrets in the same family are tried in order.
-- **HMAC rotation** (`secrets.hmac.*`) rotates both the API key checksum and the macaroon root
- key. Existing API keys and macaroons remain valid as long as the previous secret is in
- `retired`.
-- **Pagination rotation** (`secrets.pagination.*` or `secrets.default.*`) only affects
- `next_page_token` values. Outstanding tokens decode for as long as the previous secret stays
- in `retired`.
+- **HMAC rotation** (`secrets.hmac.*`) rotates both the API key checksum and the macaroon root key. Existing API keys and
+ macaroons remain valid as long as the previous secret is in `retired`.
+- **Pagination rotation** (`secrets.pagination.*` or `secrets.default.*`) only affects `next_page_token` values. Outstanding
+ tokens decode for as long as the previous secret stays in `retired`.
The two families are independent. Rotate them on independent schedules.
@@ -54,14 +49,12 @@ Multi-tenant deployments use Network IDs (NID) for data isolation:
- **Database**: Composite primary keys `(nid, key_id)` prevent cross-tenant access
- **Token claims**: NID is embedded in derived tokens and validated during verification
-- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different
- hashes per tenant
+- **Imported key hashing**: NID is included in the hash salt, so the same raw key produces different hashes per tenant
## Cache security
-Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis
-keys, or memory cache entries. This prevents credential leakage through cache inspection, Redis
-`MONITOR` commands, or memory dumps.
+Cache keys use SHA-256 hashes of API credentials. Raw credentials never appear in cache keys, Redis keys, or memory cache entries.
+This prevents credential leakage through cache inspection, Redis `MONITOR` commands, or memory dumps.
- **Cache key format:** `namespace:nid:sha256(credential)` -- deterministic, no plaintext
- **Reverse index:** Stores `key_id → sha256(credential)` for invalidation lookups -- no raw secrets
@@ -69,28 +62,25 @@ keys, or memory cache entries. This prevents credential leakage through cache in
## Admin/data plane separation
-The admin plane (key management) and data plane (verification) can be deployed separately. The admin
-plane should be restricted to internal networks. The data plane can be exposed publicly.
+The admin plane (key management) and data plane (verification) can be deployed separately. The admin plane should be restricted to
+internal networks. The data plane can be exposed publicly.
## Key lifecycle
-Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is
-irreversible. Expired keys are rejected during verification.
+Keys transition through defined states: `ACTIVE` -> `REVOKED` or `EXPIRED`. Revocation is irreversible. Expired keys are rejected
+during verification.
## Why HMAC over bcrypt
-Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen
-passwords with ~40-60 bits of entropy). They use intentional slowness (~100ms per hash) to make
-brute-force attacks against weak passwords expensive.
+Password hashing algorithms like bcrypt are designed for **low-entropy** inputs (human-chosen passwords with ~40-60 bits of
+entropy). They use intentional slowness (~100ms per hash) to make brute-force attacks against weak passwords expensive.
-API keys are fundamentally different. They are **cryptographically random** with 128+ bits of
-entropy, making dictionary attacks impossible. The key space of 2^128 (~3.4 × 10^38) renders brute
-force infeasible regardless of hashing speed.
+API keys are fundamentally different. They are **cryptographically random** with 128+ bits of entropy, making dictionary attacks
+impossible. The key space of 2^128 (~3.4 × 10^38) renders brute force infeasible regardless of hashing speed.
-HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the
-database. A database breach alone is insufficient to verify candidate keys -- the attacker must also
-compromise the secret. This provides a stronger security boundary than bcrypt, which stores
-everything needed for verification in the database itself.
+HMAC-SHA256 is a **keyed** hash function. The HMAC secret is stored in a vault, never in the database. A database breach alone is
+insufficient to verify candidate keys -- the attacker must also compromise the secret. This provides a stronger security boundary
+than bcrypt, which stores everything needed for verification in the database itself.
### Performance comparison
@@ -105,11 +95,11 @@ This yields a roughly **1,000x cost reduction** in compute for verification work
### Attack model
-**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault).
-Without the secret, they cannot verify any candidate key against the stored hashes.
+**Database breach:** The attacker obtains HMAC hashes but not the HMAC secret (stored in vault). Without the secret, they cannot
+verify any candidate key against the stored hashes.
-**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes
-exhaustive search computationally infeasible with current or foreseeable technology.
+**Brute force with secret:** Even if the attacker obtains the HMAC secret, the 2^128 key space makes exhaustive search
+computationally infeasible with current or foreseeable technology.
## Why Ed25519 for token signing
@@ -122,31 +112,29 @@ Talos uses Ed25519 (EdDSA over Curve25519) as the default signing algorithm for
| Signature size | 64 bytes | 256 bytes |
| Security level | 128 bits | 112 bits |
-Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of
-implementation vulnerabilities (unlike ECDSA P-256, where a weak nonce leaks the private key). It is
-also constant-time by design, providing immunity to timing side-channel attacks.
+Ed25519 is **deterministic** -- it does not require a random nonce, eliminating an entire class of implementation vulnerabilities
+(unlike ECDSA P-256, where a weak nonce leaks the private key). It is also constant-time by design, providing immunity to timing
+side-channel attacks.
-RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not
-support EdDSA. The signing algorithm is determined by the `alg` field in the JWK configuration.
+RSA-2048 (RS256) is supported for **legacy compatibility** when integrating with systems that do not support EdDSA. The signing
+algorithm is determined by the `alg` field in the JWK configuration.
## Security requirements
For the cryptographic model to hold, the following operational requirements must be met:
-1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g.,
- HashiCorp Vault, AWS Secrets Manager). It must never be stored in the database or committed to
- version control. Talos supports zero-downtime rotation by maintaining current and retired
- secrets.
+1. **HMAC secret management** -- The HMAC secret must be stored in a secrets manager or vault (e.g., HashiCorp Vault, AWS Secrets
+ Manager). It must never be stored in the database or committed to version control. Talos supports zero-downtime rotation by
+ maintaining current and retired secrets.
-2. **Key entropy** -- API keys must be generated using a cryptographically secure random number
- generator with at least 128 bits of entropy. Talos generates keys internally; user-provided key
- material is not accepted for issued keys.
+2. **Key entropy** -- API keys must be generated using a cryptographically secure random number generator with at least 128 bits
+ of entropy. Talos generates keys internally; user-provided key material is not accepted for issued keys.
-3. **Transport security** -- All communication must use TLS. API key secrets must never appear in
- URLs, query parameters, or log output.
+3. **Transport security** -- All communication must use TLS. API key secrets must never appear in URLs, query parameters, or log
+ output.
-4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored
- securely and never exposed through API responses or logs.
+4. **Signing key protection** -- Ed25519 and RSA private keys used for JWT signing must be stored securely and never exposed
+ through API responses or logs.
## Industry precedent
@@ -157,5 +145,5 @@ Major cloud providers use HMAC for API key authentication:
- **Stripe** -- HMAC for API authentication and webhook signature verification
- **GitHub** -- HMAC-SHA256 for webhook payload signatures
-These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and
-verification throughput is a critical operational requirement.
+These systems share the same rationale: high-entropy keys do not benefit from slow hashing, and verification throughput is a
+critical operational requirement.
diff --git a/docs/talos/concepts/token-derivation-security.md b/docs/talos/concepts/token-derivation-security.md
index ab9f4f8874..2cb37e35de 100644
--- a/docs/talos/concepts/token-derivation-security.md
+++ b/docs/talos/concepts/token-derivation-security.md
@@ -7,26 +7,20 @@ description: Stateless verification model and revocation semantics for derived t
## Overview
-Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are
-**stateless capability tokens**: all security constraints are enforced at creation time, and
-verification requires no database access. This design gives predictable sub-millisecond
-verification, zero database load on the hot path, and straightforward edge deployment.
+Talos derives short-lived JWTs and macaroons from long-lived API keys. These derived tokens are **stateless capability tokens**:
+all security constraints are enforced at creation time, and verification requires no database access. This design gives
+predictable sub-millisecond verification, zero database load on the hot path, and straightforward edge deployment.
## Creation-time enforcement
-When a token is derived via `POST /v2alpha1/tokens:derive`, all security constraints are enforced before
-the token is signed:
+When a token is derived via `POST /v2alpha1/tokens:derive`, all security constraints are enforced before the token is signed:
- **Parent key must be ACTIVE.** A revoked or expired parent key cannot produce new tokens.
-- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than
- the parent, never more.
-- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the
- parent key's expiration.
-- **Subject and owner are inherited.** These fields are copied from the parent and cannot be
- overridden.
+- **Scopes must be a subset of the parent.** The derived token can have equal or fewer scopes than the parent, never more.
+- **TTL cannot exceed the parent's remaining lifetime.** The derived token expires at or before the parent key's expiration.
+- **Subject and owner are inherited.** These fields are copied from the parent and cannot be overridden.
-If any constraint is violated, the derivation request fails with an appropriate error code. No token
-is issued.
+If any constraint is violated, the derivation request fails with an appropriate error code. No token is issued.
## Verification-time behavior
@@ -35,13 +29,11 @@ Verifying a derived token is purely cryptographic. The system checks:
1. **Signature validity** -- the token was signed by a trusted JWK signing key.
2. **Expiration** -- the `exp` claim has not passed.
-There are no database lookups, no parent key status checks, and no scope re-validation against the
-parent. This produces:
+There are no database lookups, no parent key status checks, and no scope re-validation against the parent. This produces:
- **Low latency.** Verification completes in 1-2 ms compared to 5-10 ms with database round-trips.
- **Zero database load.** Derived token verification never touches the database.
-- **Edge deployability.** Verification nodes need only the public JWK set, not a database
- connection.
+- **Edge deployability.** Verification nodes need only the public JWK set, not a database connection.
- **High availability.** Verification is unaffected by database outages.
## Revocation model
@@ -49,30 +41,25 @@ parent. This produces:
When a parent API key is revoked:
- **New derivations are blocked.** Any attempt to derive from the revoked parent returns an error.
-- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and
- the token has not expired.
-- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a
- revocation error.
+- **Existing tokens remain valid until they expire.** The cryptographic signature is still valid and the token has not expired.
+- **The parent key itself is immediately rejected.** Direct verification of the parent key returns a revocation error.
This behavior is intentional. It provides:
-- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full
- TTL.
-- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions
- simultaneously.
+- **Predictable token lifetimes.** Applications can rely on tokens remaining valid for their full TTL.
+- **No cascading failures.** Revoking a parent does not invalidate thousands of active sessions simultaneously.
- **Graceful degradation.** Downstream systems have time to transition before tokens expire.
## Immediate revocation strategies
-If your threat model requires faster invalidation of derived tokens, use one or more of these
-approaches:
+If your threat model requires faster invalidation of derived tokens, use one or more of these approaches:
-- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently
- with minimal overhead. This is the primary recommended approach.
-- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos.
- Check the deny list during your application's authorization step.
-- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature
- verification immediately. This invalidates all derived tokens, not just those from one parent.
+- **Short TTLs.** Set derived token TTLs to 5-15 minutes. Services can re-derive tokens frequently with minimal overhead. This is
+ the primary recommended approach.
+- **External deny lists.** Maintain a deny list of revoked token IDs (`jti` claims) outside Talos. Check the deny list during your
+ application's authorization step.
+- **Key rotation.** Rotate the JWK signing keys. Tokens signed with the old key will fail signature verification immediately. This
+ invalidates all derived tokens, not just those from one parent.
## TTL guidelines
@@ -83,18 +70,15 @@ approaches:
| Sensitive operations | 1-5 min | Limits damage from token theft |
| Long-running batch jobs | Use parent key directly | Avoids re-derivation during long processes |
-Short TTLs are the simplest and most effective control. When combined with the stateless
-verification model, they give security properties equivalent to stateful parent-status checks
-without the latency or availability cost.
+Short TTLs are the simplest and most effective control. When combined with the stateless verification model, they give security
+properties equivalent to stateful parent-status checks without the latency or availability cost.
## Security properties
Derived tokens are capability tokens with time-bounded authority:
-1. **All constraints enforced at creation.** The token can only be issued if the parent passes all
- checks.
-2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered
- with.
+1. **All constraints enforced at creation.** The token can only be issued if the parent passes all checks.
+2. **Cryptographically unforgeable.** Tokens are signed with EdDSA or RS256 and cannot be tampered with.
3. **Time-bounded exposure.** Short TTLs limit the window in which a compromised token is useful.
4. **Immutable claims.** Subject, owner, scopes, and expiry are sealed in the token.
5. **No privilege escalation.** Scopes can never exceed the parent's scopes at creation time.
@@ -102,4 +86,4 @@ Derived tokens are capability tokens with time-bounded authority:
## Next steps
- [Security model](security-model.md) -- cryptographic primitives and tenant isolation
-- [Derive tokens](../integrate/derive-tokens.md) -- integration guide for the token derivation API
+- [Derive tokens](../integrate/derive-tokens.mdx) -- integration guide for the token derivation API
diff --git a/docs/talos/concepts/token-format.md b/docs/talos/concepts/token-format.md
index 9651a6f663..00519c7dd8 100644
--- a/docs/talos/concepts/token-format.md
+++ b/docs/talos/concepts/token-format.md
@@ -21,10 +21,9 @@ Issued API keys follow a structured v1 format:
## How it works
-The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used
-for database lookup. The checksum is HMAC-SHA256 over the payload, enabling tamper detection.
+The identifier contains a Unix timestamp and UUID v4, Base58-encoded. The UUID is the `key_id` used for database lookup. The
+checksum is HMAC-SHA256 over the payload, enabling tamper detection.
-During verification, all configured secrets (current + retired) are tried, supporting zero-downtime
-secret rotation.
+During verification, all configured secrets (current + retired) are tried, supporting zero-downtime secret rotation.
See [Token format reference](../reference/token-format.md) for the full specification.
diff --git a/docs/talos/index.md b/docs/talos/index.md
index ca2edca1b5..7836d6e7f6 100644
--- a/docs/talos/index.md
+++ b/docs/talos/index.md
@@ -5,13 +5,12 @@ slug: /
# Ory Talos
-Ory Talos is an API key management service. It handles the full lifecycle of API credentials:
-issuing keys, verifying them on the data plane, deriving short-lived tokens (JWT and macaroon), and
-revoking access. Verification is sub-millisecond on a warm cache and stays under 5 ms p99 against a
-local SQL backend on commodity hardware.
+Ory Talos is an API key management service. It handles the full lifecycle of API credentials: issuing keys, verifying them on the
+data plane, deriving short-lived tokens (JWT and macaroon), and revoking access. Verification is sub-millisecond on a warm cache
+and stays under 5 ms p99 against a local SQL backend on commodity hardware.
-Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations**
-(verify, self-revoke) so you can scale and secure each path independently.
+Talos separates **admin operations** (issue, rotate, revoke, derive) from **data-plane operations** (verify, self-revoke) so you
+can scale and secure each path independently.
## Choose your path
@@ -19,37 +18,30 @@ Talos separates **admin operations** (issue, rotate, revoke, derive) from **data
You're a developer building an application that needs API key authentication. Start here:
-- **[Quickstart](./quickstart/index.md)** — issue and verify your first API key in 5 minutes
-- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying,
- importing keys, and deriving tokens
-- **[Error handling](./integrate/error-handling.md)** — error codes and retry strategies
+- **[Quickstart](./quickstart/index.mdx)** — issue and verify your first API key in 5 minutes
+- **[Integration guide](./integrate/index.md)** — full API walkthrough for issuing, verifying, importing keys, and deriving tokens
+- **[Error handling](./integrate/error-handling.mdx)** — error codes and retry strategies
### I want to run Talos in production
You're a platform engineer responsible for deploying and operating Talos. Start here:
- **[Install](./operate/install.md)** — binary install or build from source
-- **[Configure](./operate/configure.md)** — configuration file, environment variables, and
- hot-reload behavior
-- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane
- topologies
-- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and
- health endpoints
+- **[Configure](./operate/configure.md)** — configuration file, environment variables, and hot-reload behavior
+- **[Deploy](./operate/deploy/index.md)** — Docker, Kubernetes, and split admin/data plane topologies
+- **[Monitor](./operate/monitoring/index.md)** — Prometheus metrics, OpenTelemetry tracing, and health endpoints
## Editions
-**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key
-lifecycle, token derivation, and CLI.
+**Ory Talos OSS** (Apache 2.0) runs on a single node with a SQLite backend. It includes the full key lifecycle, token derivation,
+and CLI.
-**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed
-caching (Redis, in-memory), edge proxy nodes, and the admin UI. Pages that cover commercial-only
-features are marked with a "Commercial" badge.
+**Ory Talos Commercial** adds multi-tenancy, PostgreSQL/MySQL/CockroachDB backends, distributed caching (Redis, in-memory), edge
+proxy nodes, and the admin UI. Pages that cover commercial-only features are marked with a "Commercial" badge.
## Learn more
-- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching
- behavior
-- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint
- documentation
+- **[Concepts](./concepts/index.md)** — architecture, credential types, security model, and caching behavior
+- **[API reference](./reference/api/ory-talos-api.info.mdx)** — full admin and data plane endpoint documentation
- **[CLI reference](./reference/index.md)** — command-line tool documentation
-- **[Configuration reference](./reference/config.md)** — all configuration keys and their defaults
+- **[Configuration reference](./reference/config.mdx)** — all configuration keys and their defaults
diff --git a/docs/talos/integrate/batch-operations.md b/docs/talos/integrate/batch-operations.mdx
similarity index 72%
rename from docs/talos/integrate/batch-operations.md
rename to docs/talos/integrate/batch-operations.mdx
index f81bda5d11..e6ad836d37 100644
--- a/docs/talos/integrate/batch-operations.md
+++ b/docs/talos/integrate/batch-operations.mdx
@@ -3,12 +3,13 @@ title: Batch operations
description: Verify and import multiple credentials in a single request
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Batch operations
-Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in
-parallel and return per-item results.
+Talos supports batch endpoints for high-throughput scenarios. Batch operations process items in parallel and return per-item
+results.
@@ -21,18 +22,16 @@ First, issue two keys to use in batch operations:
```bash
-KEY1=$(talos keys issue "batch-key-1" \
+export KEY1=$(talos keys issue "batch-key-1" \
--actor user_1 --scopes "read" \
--format json \
- -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
+ -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')
-KEY2=$(talos keys issue "batch-key-2" \
+export KEY2=$(talos keys issue "batch-key-2" \
--actor user_2 --scopes "write" \
--format json \
- -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
+ -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')
-echo "export KEY1=$KEY1" >> "$DOCTEST_ENV_FILE"
-echo "export KEY2=$KEY2" >> "$DOCTEST_ENV_FILE"
echo "Keys issued"
```
@@ -40,18 +39,16 @@ echo "Keys issued"
```bash
-KEY1=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
+export KEY1=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"batch-key-1","actor_id":"user_1","scopes":["read"]}' | \
- jq -r '.secret')
+ jq -er '.secret')
-KEY2=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
+export KEY2=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"batch-key-2","actor_id":"user_2","scopes":["write"]}' | \
- jq -r '.secret')
+ jq -er '.secret')
-echo "export KEY1=$KEY1" >> "$DOCTEST_ENV_FILE"
-echo "export KEY2=$KEY2" >> "$DOCTEST_ENV_FILE"
echo "Keys issued"
```
@@ -94,11 +91,9 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:batchVerify" \
### Response format
The response contains a `results` array. Each element has the same fields as a single
-[verify response](./issue-and-verify.md#verification-response). Results are returned in the same
-order as the requests.
+[verify response](./issue-and-verify.mdx#verification-response). Results are returned in the same order as the requests.
-Invalid credentials return `active: false` with an `error_code` — they do not cause the batch
-request to fail.
+Invalid credentials return `active: false` with an `error_code` — they do not cause the batch request to fail.
### Limits
@@ -146,13 +141,12 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
### Response format
-The response includes a `results` array with per-item outcomes, plus `success_count` and
-`failure_count` counters. The HTTP response is `200 OK` if at least one key succeeds. Check
-`failure_count` and individual `error_code` fields to detect partial failures.
+The response includes a `results` array with per-item outcomes, plus `success_count` and `failure_count` counters. The HTTP
+response is `200 OK` if at least one key succeeds. Check `failure_count` and individual `error_code` fields to detect partial
+failures.
For the complete field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch
-import error codes, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
[error codes reference](../reference/error-codes.md#batch-import-error-codes).
### Limits
@@ -163,5 +157,5 @@ import error codes, see the
## Next steps
-- [Import keys](import-keys.md) — single key import with full field reference
-- [Issue and verify](issue-and-verify.md) — create and verify individual keys
+- [Import keys](import-keys.mdx) — single key import with full field reference
+- [Issue and verify](issue-and-verify.mdx) — create and verify individual keys
diff --git a/docs/talos/integrate/derive-tokens.md b/docs/talos/integrate/derive-tokens.mdx
similarity index 70%
rename from docs/talos/integrate/derive-tokens.md
rename to docs/talos/integrate/derive-tokens.mdx
index 6780175274..0fa32a2f3a 100644
--- a/docs/talos/integrate/derive-tokens.md
+++ b/docs/talos/integrate/derive-tokens.mdx
@@ -3,19 +3,18 @@ title: Derive tokens
description: Mint short-lived JWT or macaroon tokens from API keys
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Derive tokens
-Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived
-tokens when you need:
+Token derivation creates short-lived JWT or macaroon tokens from a long-lived API key. Use derived tokens when you need:
- **Browser-safe credentials** — JWTs can be verified client-side without hitting the server.
- **Temporary access** — grant time-limited access with a subset of the parent key's scopes.
- **Custom claims** — embed application-specific data in the token.
-Derived tokens inherit permissions from the parent API key and can be verified on the same data
-plane endpoint.
+Derived tokens inherit permissions from the parent API key and can be verified on the same data plane endpoint.
@@ -36,8 +35,7 @@ RESPONSE=$(talos keys issue "derive-test" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
```
@@ -50,8 +48,7 @@ ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$ISSUE_RESP" | jq .
-API_SECRET=$(echo "$ISSUE_RESP" | jq -r '.secret')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$ISSUE_RESP" | jq -er '.secret')
```
@@ -76,8 +73,7 @@ RESPONSE=$(talos keys derive-token "$API_SECRET" \
echo "$RESPONSE" | jq .
-JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+export JWT_TOKEN=$(echo "$RESPONSE" | jq -er '.token.token')
```
@@ -96,8 +92,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
echo "$RESPONSE" | jq .
-JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+export JWT_TOKEN=$(echo "$RESPONSE" | jq -er '.token.token')
```
@@ -105,19 +100,17 @@ echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or
-`TOKEN_ALGORITHM_MACAROON`), optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For
-the complete field reference, see the
+The key fields are `credential` (the parent API key secret), `algorithm` (`TOKEN_ALGORITHM_JWT` or `TOKEN_ALGORITHM_MACAROON`),
+optional `ttl`, `scopes` (subset of parent's), and `custom_claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
-For HTTP API requests, `ttl` accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds
-like `1y6mo` in addition to standard Go durations. The current CLI `--ttl` flag still expects
-standard Go durations such as `1h` or `30m`.
+For HTTP API requests, `ttl` accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo` in addition to
+standard Go durations. The current CLI `--ttl` flag still expects standard Go durations such as `1h` or `30m`.
### Response
-The response contains a `token` object with `token.token` (the derived token string),
-`token.expire_time`, `token.scopes`, and `token.claims`. For the complete field reference, see the
+The response contains a `token` object with `token.token` (the derived token string), `token.expire_time`, `token.scopes`, and
+`token.claims`. For the complete field reference, see the
[DeriveToken API reference](../reference/api/admin-derive-token.api.mdx).
## Verify a derived token
@@ -190,8 +183,7 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
## JWKS endpoint
-For client-side JWT verification, fetch the public keys from the JWKS endpoint at
-`/v2alpha1/admin/derivedKeys/jwks.json`:
+For client-side JWT verification, fetch the public keys from the JWKS endpoint at `/v2alpha1/admin/derivedKeys/jwks.json`:
@@ -212,14 +204,12 @@ curl -s "$TALOS_URL/v2alpha1/admin/derivedKeys/jwks.json" | jq .
-The endpoint serves the active public signing keys plus any retired keys still inside the
-verification window. Each entry includes a `kid` field that matches the `kid` header on tokens
-signed with that key.
+The endpoint serves the active public signing keys plus any retired keys still inside the verification window. Each entry includes
+a `kid` field that matches the `kid` header on tokens signed with that key.
### Client-side caching and refresh
-Cache the JWKS response on the client so verification does not call Talos on every request.
-Recommended settings:
+Cache the JWKS response on the client so verification does not call Talos on every request. Recommended settings:
| Setting | Recommended value | Notes |
| -------------------- | ----------------- | ------------------------------------------------------- |
@@ -227,25 +217,22 @@ Recommended settings:
| Refresh-on-miss | Enabled | If a token's `kid` is unknown, refetch JWKS once. |
| Refresh failure mode | Serve stale | If the refetch fails, keep the previous keys until TTL. |
-Most mature JWT libraries (`jose` for Node, `PyJWT`/`PyJWKClient` for Python, `go-jose`,
-`jjwt` for Java) support these patterns natively — set the cache TTL and enable
-refresh-on-unknown-kid. Do not poll the endpoint on a fixed interval shorter than 1 minute; it adds
-load without changing the practical revocation window, which is bounded by the longest issued
-token TTL.
+Most mature JWT libraries (`jose` for Node, `PyJWT`/`PyJWKClient` for Python, `go-jose`, `jjwt` for Java) support these patterns
+natively — set the cache TTL and enable refresh-on-unknown-kid. Do not poll the endpoint on a fixed interval shorter than 1
+minute; it adds load without changing the practical revocation window, which is bounded by the longest issued token TTL.
-When you rotate signing keys, keep the previous key in the JWKS response (mark it retired in the
-server config, do not delete the JWK) for at least the longest issued token TTL plus the maximum
-client cache TTL. Otherwise clients with a freshly cached JWKS that lacks the new `kid` can reject
-valid tokens until their cache expires.
+When you rotate signing keys, keep the previous key in the JWKS response (mark it retired in the server config, do not delete the
+JWK) for at least the longest issued token TTL plus the maximum client cache TTL. Otherwise clients with a freshly cached JWKS
+that lacks the new `kid` can reject valid tokens until their cache expires.
## Scope restrictions
-Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any
-scope that the parent key does not have, the request fails with a `403 Forbidden` error. To restrict
-scopes, request only scopes that exist on the parent key.
+Derived tokens can only have scopes that are a subset of the parent key's scopes. If you request any scope that the parent key
+does not have, the request fails with a `403 Forbidden` error. To restrict scopes, request only scopes that exist on the parent
+key.
## Next steps
-- [Issue and verify](issue-and-verify.md) — create the parent API keys used for derivation
-- [Key lifecycle](key-lifecycle.md) — rotate and revoke parent keys
-- [Self-revocation](self-revocation.md) — allow key holders to revoke their own keys
+- [Issue and verify](issue-and-verify.mdx) — create the parent API keys used for derivation
+- [Key lifecycle](key-lifecycle.mdx) — rotate and revoke parent keys
+- [Self-revocation](self-revocation.mdx) — allow key holders to revoke their own keys
diff --git a/docs/talos/integrate/error-handling.md b/docs/talos/integrate/error-handling.mdx
similarity index 70%
rename from docs/talos/integrate/error-handling.md
rename to docs/talos/integrate/error-handling.mdx
index b41d588fcb..9a6d095be7 100644
--- a/docs/talos/integrate/error-handling.md
+++ b/docs/talos/integrate/error-handling.mdx
@@ -3,12 +3,13 @@ title: Error handling
description: Error response format, error codes, and retry logic
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Error handling
-All Talos API errors follow the [google.rpc.Status](https://cloud.google.com/apis/design/errors#error_model)
-shape. This guide covers the error response structure, common error codes, and retry strategies.
+All Talos API errors follow the [google.rpc.Status](https://cloud.google.com/apis/design/errors#error_model) shape. This guide
+covers the error response structure, common error codes, and retry strategies.
@@ -40,24 +41,22 @@ Every non-2xx response uses the `google.rpc.Status` envelope:
| `message` | Human-readable summary. Suitable for logging, not for end-user display. |
| `details` | Optional list of typed error details. `ErrorInfo` carries the machine-readable `reason`. |
-The HTTP status code is set from the canonical
-[gRPC-to-HTTP mapping](https://cloud.google.com/apis/design/errors#http_mapping). For example, code
-`5` (`NOT_FOUND`) returns HTTP 404; code `7` (`PERMISSION_DENIED`) returns HTTP 403.
+The HTTP status code is set from the canonical [gRPC-to-HTTP mapping](https://cloud.google.com/apis/design/errors#http_mapping).
+For example, code `5` (`NOT_FOUND`) returns HTTP 404; code `7` (`PERMISSION_DENIED`) returns HTTP 403.
### Reading the reason
-The stable, machine-readable identifier is `details[*].reason` on the `ErrorInfo` detail. Match on
-`reason` — never on `message`, which can change between releases.
+The stable, machine-readable identifier is `details[*].reason` on the `ErrorInfo` detail. Match on `reason` — never on `message`,
+which can change between releases.
```bash
-REASON=$(echo "$RESPONSE" | jq -r '.details[]? | select(."@type" | endswith("ErrorInfo")).reason')
+REASON=$(echo "$RESPONSE" | jq -er '.details[]? | select(."@type" | endswith("ErrorInfo")).reason')
```
## Verification errors
-The verify endpoint (`POST /v2alpha1/admin/apiKeys:verify`) is the one exception. A verification
-failure is part of the normal verification result, not a transport-level error, so it returns
-`200 OK` with `is_active: false` and a structured error code:
+The verify endpoint (`POST /v2alpha1/admin/apiKeys:verify`) is the one exception. A verification failure is part of the normal
+verification result, not a transport-level error, so it returns `200 OK` with `is_active: false` and a structured error code:
```json
{
@@ -67,17 +66,15 @@ failure is part of the normal verification result, not a transport-level error,
}
```
-Treat the response as successful; act on `is_active` and `error_code`. Only fall back to the
-`google.rpc.Status` handling above when the HTTP status is not 2xx (for example, the verify request
-itself was malformed).
+Treat the response as successful; act on `is_active` and `error_code`. Only fall back to the `google.rpc.Status` handling above
+when the HTTP status is not 2xx (for example, the verify request itself was malformed).
For the complete list of verification error codes (`VERIFICATION_ERROR_*`), see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
## HTTP status codes
-For the complete list of HTTP status codes and reasons, see the
-[error codes reference](../reference/error-codes.md).
+For the complete list of HTTP status codes and reasons, see the [error codes reference](../reference/error-codes.md).
Key categories:
@@ -88,22 +85,18 @@ Key categories:
### Safe to retry
-- **`UNAVAILABLE` (HTTP 503)** — the server is temporarily overloaded. Retry with exponential
- backoff.
+- **`UNAVAILABLE` (HTTP 503)** — the server is temporarily overloaded. Retry with exponential backoff.
- **`DEADLINE_EXCEEDED` (HTTP 504)** — the request timed out. Retry with backoff.
- **Network errors** — connection refused, DNS failure, etc. Retry with backoff.
### Not safe to retry without an idempotency key
-- **`ALREADY_EXISTS` (HTTP 409)** — the resource already exists. Read the existing resource and
- reconcile.
-- **`INVALID_ARGUMENT` (HTTP 400)** / **`FAILED_PRECONDITION` (HTTP 400)** — fix the request before
- retrying.
+- **`ALREADY_EXISTS` (HTTP 409)** — the resource already exists. Read the existing resource and reconcile.
+- **`INVALID_ARGUMENT` (HTTP 400)** / **`FAILED_PRECONDITION` (HTTP 400)** — fix the request before retrying.
### Idempotency key
-When issuing API keys, include `request_id` in the request body. This field is stored on the key
-for client-side deduplication:
+When issuing API keys, include `request_id` in the request body. This field is stored on the key for client-side deduplication:
@@ -131,8 +124,8 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-The `request_id` is recorded in the key's metadata. The server does not enforce server-side
-idempotent replay — sending the same `request_id` twice creates two keys.
+The `request_id` is recorded in the key's metadata. The server does not enforce server-side idempotent replay — sending the same
+`request_id` twice creates two keys.
## Recommended backoff
@@ -148,5 +141,5 @@ Add jitter (random 0-50% of the wait time) to avoid thundering-herd effects.
## Next steps
-- [Issue and verify](issue-and-verify.md) — verification response format
-- [Batch operations](batch-operations.md) — partial failure handling
+- [Issue and verify](issue-and-verify.mdx) — verification response format
+- [Batch operations](batch-operations.mdx) — partial failure handling
diff --git a/docs/talos/integrate/import-keys.md b/docs/talos/integrate/import-keys.mdx
similarity index 76%
rename from docs/talos/integrate/import-keys.md
rename to docs/talos/integrate/import-keys.mdx
index d5448ea7e6..e16a268ab5 100644
--- a/docs/talos/integrate/import-keys.md
+++ b/docs/talos/integrate/import-keys.mdx
@@ -3,23 +3,22 @@ title: Import existing keys
description: Import API keys from external systems into Talos
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Import existing keys
-Talos can manage API keys that were created outside the system. Import lets you migrate from a
-legacy key management solution or centralize keys from multiple providers without rotating
-credentials. For large migrations, use the batchImport API to import up to 1000 keys in a single
-request.
+Talos can manage API keys that were created outside the system. Import lets you migrate from a legacy key management solution or
+centralize keys from multiple providers without rotating credentials. For large migrations, use the batchImport API to import up
+to 1000 keys in a single request.
## How import works
-When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original
-key is never stored. Verification works by computing the same hash and looking it up in the
-database.
+When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original key is never stored.
+Verification works by computing the same hash and looking it up in the database.
-Imported keys support the same features as issued keys: scopes, metadata, expiration, token
-derivation (JWT/macaroon), and revocation.
+Imported keys support the same features as issued keys: scopes, metadata, expiration, token derivation (JWT/macaroon), and
+revocation.
@@ -43,8 +42,7 @@ RESPONSE=$(talos keys imported import "Stripe production key" \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.imported_api_key.key_id')
```
@@ -64,8 +62,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
-echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')
```
@@ -73,16 +70,14 @@ echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`,
-`ttl`, and `metadata`. For the complete field reference, see the
-[ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+The key fields are `raw_key` (the actual API key string), `name`, `actor_id`, and optional `scopes`, `ttl`, and `metadata`. For
+the complete field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
The response returns an `imported_api_key` object. The `raw_key` is **never returned** after import.
## Verify an imported key
-Imported keys use the same verification endpoint as issued keys. The data plane automatically
-detects the credential type:
+Imported keys use the same verification endpoint as issued keys. The data plane automatically detects the credential type:
@@ -142,13 +137,11 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
### Batch response
-The response includes a `results` array with per-item outcomes (`imported_api_key` on success,
-`error_code` and `error_message` on failure), plus `success_count` and `failure_count` counters. If
-at least one key succeeds, the HTTP response is `200 OK`.
+The response includes a `results` array with per-item outcomes (`imported_api_key` on success, `error_code` and `error_message` on
+failure), plus `success_count` and `failure_count` counters. If at least one key succeeds, the HTTP response is `200 OK`.
For the complete response field reference, see the
-[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch
-import error codes, see the
+[BatchImportAPIKeys API reference](../reference/api/admin-batch-import-api-keys.api.mdx). For batch import error codes, see the
[error codes reference](../reference/error-codes.md#batch-import-error-codes).
## List imported keys
@@ -232,6 +225,6 @@ Delete is permanent and irreversible. Prefer revocation for audit trail.
## Next steps
-- [Batch operations](batch-operations.md) -- batch verify and batch import in detail
-- [Key lifecycle](key-lifecycle.md) -- update, rotate, and revoke keys
-- [Derive tokens](derive-tokens.md) -- mint JWTs or macaroons from imported keys
+- [Batch operations](batch-operations.mdx) -- batch verify and batch import in detail
+- [Key lifecycle](key-lifecycle.mdx) -- update, rotate, and revoke keys
+- [Derive tokens](derive-tokens.mdx) -- mint JWTs or macaroons from imported keys
diff --git a/docs/talos/integrate/index.md b/docs/talos/integrate/index.md
index c967589137..6cd573e6b5 100644
--- a/docs/talos/integrate/index.md
+++ b/docs/talos/integrate/index.md
@@ -7,53 +7,51 @@ description: Add API key authentication to your application
Ory Talos exposes two logical planes that map to distinct responsibilities:
-- **Admin plane** — Create, update, rotate, and revoke API keys. Deploy behind your internal
- network or VPN. All admin endpoints live under `/v2alpha1/admin/...`.
-- **Data plane** — Verify credentials with low latency and let key holders revoke their own keys.
- The two public verification endpoints are `POST /v2alpha1/admin/apiKeys:verify` and
- `POST /v2alpha1/admin/apiKeys:batchVerify`; the self-service endpoint is
+- **Admin plane** — Create, update, rotate, and revoke API keys. Deploy behind your internal network or VPN. All admin endpoints
+ live under `/v2alpha1/admin/...`.
+- **Data plane** — Verify credentials with low latency and let key holders revoke their own keys. The two public verification
+ endpoints are `POST /v2alpha1/admin/apiKeys:verify` and `POST /v2alpha1/admin/apiKeys:batchVerify`; the self-service endpoint is
`POST /v2alpha1/apiKeys:selfRevoke`.
-Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the
-data plane every time a request arrives.
+Most integrations follow a simple pattern: issue keys on the admin plane, then verify them on the data plane every time a request
+arrives.
-The verify endpoints share the `/admin/` URL prefix for historical reasons. They are still safe to
-expose publicly — they take a credential and return verification metadata only — but you must
-restrict the rest of `/admin/` at your edge. See
+The verify endpoints share the `/admin/` URL prefix for historical reasons. They are still safe to expose publicly — they take a
+credential and return verification metadata only — but you must restrict the rest of `/admin/` at your edge. See
[Exposing only the verify endpoints publicly](#exposing-only-the-verify-endpoints-publicly) below.
## Common workflows
-| Task | Endpoint | Guide |
-| --------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
-| Issue a key and verify it | `POST /v2alpha1/admin/issuedApiKeys`, `POST /v2alpha1/admin/apiKeys:verify` | [Issue and verify](issue-and-verify.md) |
-| Import keys from another system | `POST /v2alpha1/admin/importedApiKeys` | [Import keys](import-keys.md) |
-| Mint short-lived JWT or macaroon tokens | `POST /v2alpha1/admin/apiKeys:derive` | [Derive tokens](derive-tokens.md) |
-| Verify many credentials at once | `POST /v2alpha1/admin/apiKeys:batchVerify` | [Batch operations](batch-operations.md) |
-| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.md) |
-| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.md) |
-| Let key holders revoke their own key | `POST /v2alpha1/apiKeys:selfRevoke` | [Self-revocation](self-revocation.md) |
-| Handle errors and retries | All endpoints | [Error handling](error-handling.md) |
+| Task | Endpoint | Guide |
+| --------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------- |
+| Issue a key and verify it | `POST /v2alpha1/admin/issuedApiKeys`, `POST /v2alpha1/admin/apiKeys:verify` | [Issue and verify](issue-and-verify.mdx) |
+| Import keys from another system | `POST /v2alpha1/admin/importedApiKeys` | [Import keys](import-keys.mdx) |
+| Mint short-lived JWT or macaroon tokens | `POST /v2alpha1/admin/apiKeys:derive` | [Derive tokens](derive-tokens.mdx) |
+| Verify many credentials at once | `POST /v2alpha1/admin/apiKeys:batchVerify` | [Batch operations](batch-operations.mdx) |
+| Update, rotate, or revoke a key | `PATCH`, `:rotate`, `:revoke` | [Key lifecycle](key-lifecycle.mdx) |
+| Enforce per-key rate limits | `rate_limit_policy` on issue/update | [Rate limiting](rate-limiting.mdx) |
+| Let key holders revoke their own key | `POST /v2alpha1/apiKeys:selfRevoke` | [Self-revocation](self-revocation.mdx) |
+| Handle errors and retries | All endpoints | [Error handling](error-handling.mdx) |
## Authentication
-The admin plane does not enforce authentication by default. Protect it at the infrastructure level
-(VPN, service mesh, reverse proxy with mTLS). The data plane is public-facing and requires no
-authentication — callers supply the credential they want to verify.
+The admin plane does not enforce authentication by default. Protect it at the infrastructure level (VPN, service mesh, reverse
+proxy with mTLS). The data plane is public-facing and requires no authentication — callers supply the credential they want to
+verify.
## Exposing only the verify endpoints publicly
-Talos has no built-in admin authentication, so do not put `/v2alpha1/admin/*` on the public
-internet. Instead, run a reverse proxy (NGINX, Envoy, HAProxy, an API gateway) in front of the
-data-plane process and allow only the verify and self-revoke paths through:
+Talos has no built-in admin authentication, so do not put `/v2alpha1/admin/*` on the public internet. Instead, run a reverse proxy
+(NGINX, Envoy, HAProxy, an API gateway) in front of the data-plane process and allow only the verify and self-revoke paths
+through:
-| Path | Method | Public | Reason |
-| -------------------------------------------- | ------ | ------ | ------------------------------------- |
-| `/v2alpha1/admin/apiKeys:verify` | POST | Yes | Verification — credential in request. |
-| `/v2alpha1/admin/apiKeys:batchVerify` | POST | Yes | Batch verification. |
-| `/v2alpha1/apiKeys:selfRevoke` | POST | Yes | Self-revocation by the key holder. |
-| `/health/alive`, `/health/ready` | GET | Maybe | Required for load-balancer probes. |
-| Everything else under `/v2alpha1/admin/...` | any | No | Issuance, rotation, admin revocation. |
+| Path | Method | Public | Reason |
+| ------------------------------------------- | ------ | ------ | ------------------------------------- |
+| `/v2alpha1/admin/apiKeys:verify` | POST | Yes | Verification — credential in request. |
+| `/v2alpha1/admin/apiKeys:batchVerify` | POST | Yes | Batch verification. |
+| `/v2alpha1/apiKeys:selfRevoke` | POST | Yes | Self-revocation by the key holder. |
+| `/health/alive`, `/health/ready` | GET | Maybe | Required for load-balancer probes. |
+| Everything else under `/v2alpha1/admin/...` | any | No | Issuance, rotation, admin revocation. |
Example NGINX snippet that fronts the data plane:
@@ -67,13 +65,13 @@ location / { return 404; }
```
Run the admin plane on a separate listener (or a separate process — see
-[Separate admin and data planes](../operate/deploy/separate-planes.md)) bound to an internal
-network so it cannot be reached even if the public proxy is misconfigured.
+[Separate admin and data planes](../operate/deploy/separate-planes.md)) bound to an internal network so it cannot be reached even
+if the public proxy is misconfigured.
## Request format
-All endpoints accept and return JSON with `Content-Type: application/json`. Field names use
-`snake_case` (for example `actor_id`, `key_id`, `expire_time`).
+All endpoints accept and return JSON with `Content-Type: application/json`. Field names use `snake_case` (for example `actor_id`,
+`key_id`, `expire_time`).
Durations accept both Go format (`168h`, `30m`, `1h30m`) and protobuf format (`604800s`).
diff --git a/docs/talos/integrate/ip-restrictions.md b/docs/talos/integrate/ip-restrictions.mdx
similarity index 77%
rename from docs/talos/integrate/ip-restrictions.md
rename to docs/talos/integrate/ip-restrictions.mdx
index 63706c527a..7af0202abf 100644
--- a/docs/talos/integrate/ip-restrictions.md
+++ b/docs/talos/integrate/ip-restrictions.mdx
@@ -3,25 +3,25 @@ title: IP restrictions
description: Restrict API key usage to specific IP addresses or CIDR ranges
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# IP restrictions
-IP restrictions let you limit which client IPs can use an API key. When enabled, verification
-rejects requests from IPs outside the allowed CIDR ranges. Keys without IP restrictions are
-unrestricted.
+IP restrictions let you limit which client IPs can use an API key. When enabled, verification rejects requests from IPs outside
+the allowed CIDR ranges. Keys without IP restrictions are unrestricted.
## Prerequisites
-A running Talos server. See the [quickstart](../quickstart/index.md) to start one locally.
+A running Talos server. See the [quickstart](../quickstart/index.mdx) to start one locally.
## Configure client IP source
-By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server
-runs behind a reverse proxy or CDN, configure the correct header in your Talos config:
+By default, Talos uses the TCP remote address (`REMOTE_ADDR`) to determine client IP. If your server runs behind a reverse proxy
+or CDN, configure the correct header in your Talos config:
```yaml
serve:
@@ -37,13 +37,12 @@ Supported values:
- `CLIENT_IP_SOURCE_X_REAL_IP` — Nginx
- `CLIENT_IP_SOURCE_TRUE_CLIENT_IP` — Cloudflare Enterprise
-This is a global setting — all IP restriction checks use the same source. Set it once to match your
-infrastructure topology.
+This is a global setting — all IP restriction checks use the same source. Set it once to match your infrastructure topology.
## Issue a key with IP restrictions
-Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both
-individual IPs (with `/32` or `/128` suffix) and CIDR ranges:
+Add the `ip_restriction` field when creating a key. The `allowed_cidrs` array accepts both individual IPs (with `/32` or `/128`
+suffix) and CIDR ranges:
@@ -59,11 +58,8 @@ RESPONSE=$(talos keys issue "restricted-key" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -82,18 +78,14 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
-For the complete request field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+For the complete request field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify from an allowed IP
@@ -126,8 +118,8 @@ The response includes the key metadata with `is_active: true`.
## Verification from a disallowed IP
-When the client IP is outside all allowed CIDR ranges, verification returns
-`VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does not reveal which CIDRs are configured.
+When the client IP is outside all allowed CIDR ranges, verification returns `VERIFICATION_ERROR_IP_NOT_ALLOWED`. The response does
+not reveal which CIDRs are configured.
For the full list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
@@ -237,17 +229,16 @@ echo "$IMPORT_RESPONSE" | jq .
-For the complete import field reference, see the
-[ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
+For the complete import field reference, see the [ImportAPIKey API reference](../reference/api/admin-import-api-key.api.mdx).
## Behavior notes
-- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key
- is unrestricted (all IPs allowed).
+- **Allowlist model**: Only listed CIDRs are permitted. An empty `allowed_cidrs` array means the key is unrestricted (all IPs
+ allowed).
- **Cache TTL**: IP restriction changes take effect after the cache TTL expires. See
[cache configuration](../operate/cache/index.md) for TTL settings.
- **Fail-closed**: If client IP resolution fails, the request is denied.
-- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and
- `/128` for single IPv6 addresses.
-- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens
- (JWTs/macaroons). Token verification checks the key's IP restrictions at derivation time.
+- **IPv4 and IPv6**: Both address families are supported. Use `/32` for single IPv4 addresses and `/128` for single IPv6
+ addresses.
+- **Derived tokens**: IP restrictions apply to the underlying API key, not to derived tokens (JWTs/macaroons). Token verification
+ checks the key's IP restrictions at derivation time.
diff --git a/docs/talos/integrate/issue-and-verify.md b/docs/talos/integrate/issue-and-verify.mdx
similarity index 64%
rename from docs/talos/integrate/issue-and-verify.md
rename to docs/talos/integrate/issue-and-verify.mdx
index 34a19703fb..09b13d269f 100644
--- a/docs/talos/integrate/issue-and-verify.md
+++ b/docs/talos/integrate/issue-and-verify.mdx
@@ -3,17 +3,16 @@ title: Issue and verify API keys
description: Create API keys on the admin plane and verify them on the data plane
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Issue and verify API keys
-This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are
-executable and tested in CI.
+This guide walks through the full lifecycle of issuing an API key and verifying it. All examples are executable and tested in CI.
## Prerequisites
-A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.md) to start
-one locally.
+A running Talos server and the `talos` CLI. See the [quickstart](../quickstart/index.mdx) to start one locally.
@@ -38,11 +37,8 @@ RESPONSE=$(talos keys issue "backend-service" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -61,11 +57,8 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')
```
@@ -73,24 +66,22 @@ echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
### Request fields
-The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`,
-`ttl`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
+The key fields are `name` (human-readable label), `actor_id` (key actor), and optional `scopes`, `ttl`, `metadata`, and
+`rate_limit_policy`. For the complete field reference, see the
[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
-For HTTP API requests, `ttl` also accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and
-compounds like `1y6mo`. The current CLI `--ttl` flag examples still use standard Go durations such
-as `720h` and `1h30m`.
+For HTTP API requests, `ttl` also accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and compounds like `1y6mo`. The
+current CLI `--ttl` flag examples still use standard Go durations such as `720h` and `1h30m`.
### Response fields
The response contains two top-level fields:
- **`issued_api_key`** — The key metadata (ID, name, actor, scopes, status, timestamps).
-- **`secret`** — The full API key credential. This value is returned **only once** and cannot be
- retrieved later. Store it securely.
+- **`secret`** — The full API key credential. This value is returned **only once** and cannot be retrieved later. Store it
+ securely.
-For the complete metadata field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+For the complete metadata field reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a key
@@ -119,25 +110,21 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
### Verification response
-The response includes `is_active` (boolean), `key_id`, `actor_id`, `issuer`, `scopes`, `metadata`,
-and `expire_time` when valid. When `is_active` is `false`, `error_code` and `error_message` indicate
-the reason. When rate limit enforcement is enabled (Commercial), the response also includes
-`rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For the
-complete field reference, see the
-[VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+The response includes `is_active` (boolean), `key_id`, `actor_id`, `issuer`, `scopes`, `metadata`, and `expire_time` when valid.
+When `is_active` is `false`, `error_code` and `error_message` indicate the reason. When rate limit enforcement is enabled
+(Commercial), the response also includes `rate_limit_remaining` and `rate_limit_reset_time` for keys with a rate limit policy. For
+the complete field reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
### Verification error codes
-When `is_active` is `false`, the `error_code` field indicates why. Common codes include
-`VERIFICATION_ERROR_EXPIRED`, `VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and
-`VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's rate limit quota is exhausted). For
-the complete list, see the
+When `is_active` is `false`, the `error_code` field indicates why. Common codes include `VERIFICATION_ERROR_EXPIRED`,
+`VERIFICATION_ERROR_REVOKED`, `VERIFICATION_ERROR_NOT_FOUND`, and `VERIFICATION_ERROR_RATE_LIMITED` (Commercial, when the key's
+rate limit quota is exhausted). For the complete list, see the
[verification error codes reference](../reference/error-codes.md#verification-error-codes).
## Cache bypass
-Verification results are cached for performance. After revoking a key, you can bypass the cache for
-immediate consistency:
+Verification results are cached for performance. After revoking a key, you can bypass the cache for immediate consistency:
```bash
curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
@@ -204,15 +191,14 @@ curl -s "$TALOS_URL/v2alpha1/admin/issuedApiKeys?page_size=10&actor_id=user_42"
### Query parameters
-Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status`
-(filtering). For the complete parameter reference, see the
-[ListIssuedAPIKeys API reference](../reference/api/admin-list-issued-api-keys.api.mdx).
+Key parameters are `page_size`, `page_token` (cursor-based pagination), `actor_id`, and `status` (filtering). For the complete
+parameter reference, see the [ListIssuedAPIKeys API reference](../reference/api/admin-list-issued-api-keys.api.mdx).
The response includes a `next_page_token` field. When empty, you have reached the last page.
## Next steps
-- [Key lifecycle](key-lifecycle.md) — update, rotate, and revoke keys
-- [Import keys](import-keys.md) — bring existing keys into Talos
-- [Derive tokens](derive-tokens.md) — mint short-lived JWTs or macaroons
-- [Error handling](error-handling.md) — error response format and retry logic
+- [Key lifecycle](key-lifecycle.mdx) — update, rotate, and revoke keys
+- [Import keys](import-keys.mdx) — bring existing keys into Talos
+- [Derive tokens](derive-tokens.mdx) — mint short-lived JWTs or macaroons
+- [Error handling](error-handling.mdx) — error response format and retry logic
diff --git a/docs/talos/integrate/key-lifecycle.md b/docs/talos/integrate/key-lifecycle.mdx
similarity index 67%
rename from docs/talos/integrate/key-lifecycle.md
rename to docs/talos/integrate/key-lifecycle.mdx
index 7ce8b266ae..52ff45a6c1 100644
--- a/docs/talos/integrate/key-lifecycle.md
+++ b/docs/talos/integrate/key-lifecycle.mdx
@@ -3,12 +3,13 @@ title: Key lifecycle
description: Update, rotate, and revoke API keys
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Key lifecycle
-After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All
-lifecycle operations use the admin plane.
+After issuing an API key, you can update its metadata, rotate the secret, or revoke it. All lifecycle operations use the admin
+plane.
@@ -30,10 +31,8 @@ RESPONSE=$(talos keys issue "lifecycle-test" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -46,24 +45,20 @@ ISSUE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$ISSUE_RESP" | jq .
-API_SECRET=$(echo "$ISSUE_RESP" | jq -r '.secret')
-KEY_ID=$(echo "$ISSUE_RESP" | jq -r '.key_id')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$ISSUE_RESP" | jq -er '.secret')
+export KEY_ID=$(echo "$ISSUE_RESP" | jq -er '.key_id')
```
-When you set `ttl` on issue or import requests, the HTTP API accepts extended formats such as `1y`,
-`1mo`, `1w`, `1d`, and compounds like `1y6mo` in addition to standard Go durations. The current CLI
-`--ttl` flags still expect standard Go duration strings; see the
-[configuration reference](../reference/config.md) for the canonical duration format summary.
+When you set `ttl` on issue or import requests, the HTTP API accepts extended formats such as `1y`, `1mo`, `1w`, `1d`, and
+compounds like `1y6mo` in addition to standard Go durations. The current CLI `--ttl` flags still expect standard Go duration
+strings; see the [configuration reference](../reference/config.mdx) for the canonical duration format summary.
## Update key metadata
-Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the
-secret:
+Use `PATCH` to update a key's name, scopes, metadata, or rate limit policy without changing the secret:
@@ -97,11 +92,10 @@ curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
### Update mask
-The `update_mask` field controls which fields are modified. Only fields listed in `paths` are
-changed. This follows the [AIP-134](https://google.aip.dev/134) standard for partial updates.
+The `update_mask` field controls which fields are modified. Only fields listed in `paths` are changed. This follows the
+[AIP-134](https://google.aip.dev/134) standard for partial updates.
-Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete
-field reference, see the
+Updatable fields include `name`, `scopes`, `metadata`, and `rate_limit_policy`. For the complete field reference, see the
[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Rotate a key
@@ -121,10 +115,8 @@ RESPONSE=$(talos keys issued rotate "$KEY_ID" \
echo "$RESPONSE" | jq .
-NEW_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-NEW_KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-echo "export API_SECRET=$NEW_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -140,10 +132,8 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys/${KEY_ID}:ro
echo "$RESPONSE" | jq .
-NEW_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-NEW_KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
-echo "export API_SECRET=$NEW_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')
```
@@ -151,8 +141,8 @@ echo "export KEY_ID=$NEW_KEY_ID" >> "$DOCTEST_ENV_FILE"
### Rotation response
-The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once),
-and `old_issued_api_key` (status `KEY_STATUS_REVOKED`). For the complete field reference, see the
+The response includes the new `issued_api_key` (with a new `key_id`), the new `secret` (shown once), and `old_issued_api_key`
+(status `KEY_STATUS_REVOKED`). For the complete field reference, see the
[RotateIssuedAPIKey API reference](../reference/api/admin-rotate-issued-api-key.api.mdx).
### Zero-downtime rotation
@@ -166,8 +156,7 @@ The `:rotate` endpoint revokes the old key immediately. For zero-downtime rotati
## Revoke a key
-Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache
-TTL):
+Revocation is irreversible. Once revoked, the key fails verification immediately (subject to cache TTL):
@@ -195,18 +184,16 @@ echo "Key revoked"
### Revocation reasons
Standard reasons include `REVOCATION_REASON_KEY_COMPROMISE`, `REVOCATION_REASON_SUPERSEDED`,
-`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only).
-For the complete list, see the
+`REVOCATION_REASON_AFFILIATION_CHANGED`, and `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` (admin only). For the complete list, see the
[RevokeAPIKey API reference](../reference/api/admin-revoke-api-key.api.mdx).
-When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable
-explanation.
+When using `PRIVILEGE_WITHDRAWN`, you can include a `reason_text` field with a human-readable explanation.
### Revocation and caching
-Revocation takes effect in the database immediately. However, if caching is enabled, previously
-cached verification results may remain valid until the cache entry expires. To force immediate
-effect, use the `Cache-Control: no-cache` header on verification requests.
+Revocation takes effect in the database immediately. However, if caching is enabled, previously cached verification results may
+remain valid until the cache entry expires. To force immediate effect, use the `Cache-Control: no-cache` header on verification
+requests.
## Verify after revocation
@@ -236,6 +223,6 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
## Next steps
-- [Self-revocation](self-revocation.md) -- let key holders revoke their own keys
-- [Issue and verify](issue-and-verify.md) -- create new keys to replace revoked ones
-- [Error handling](error-handling.md) -- handle revocation-related errors
+- [Self-revocation](self-revocation.mdx) -- let key holders revoke their own keys
+- [Issue and verify](issue-and-verify.mdx) -- create new keys to replace revoked ones
+- [Error handling](error-handling.mdx) -- handle revocation-related errors
diff --git a/docs/talos/integrate/rate-limiting.md b/docs/talos/integrate/rate-limiting.mdx
similarity index 61%
rename from docs/talos/integrate/rate-limiting.md
rename to docs/talos/integrate/rate-limiting.mdx
index fa2a28b9db..f0fc9b004c 100644
--- a/docs/talos/integrate/rate-limiting.md
+++ b/docs/talos/integrate/rate-limiting.mdx
@@ -3,27 +3,26 @@ title: Rate limiting
description: Attach and enforce rate limit policies on API keys
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Rate limiting
-Rate limit policies let you cap how many verification requests a key can serve within a time window.
-Talos stores the policy on the key, returns it in verification responses, and -- in the Commercial
-edition -- enforces it server-side. For background on how enforcement works in each edition, see the
-[rate limiting concepts page](../concepts/rate-limiting.md).
+Rate limit policies let you cap how many verification requests a key can serve within a time window. Talos stores the policy on
+the key, returns it in verification responses, and -- in the Commercial edition -- enforces it server-side. For background on how
+enforcement works in each edition, see the [rate limiting concepts page](../concepts/rate-limiting.md).
## Prerequisites
-A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.md) to
-start one locally.
+A running Talos server with rate limiting enabled. See the [quickstart](../quickstart/index.mdx) to start one locally.
## Attach a rate limit policy
-Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a
-`window` (time window as a duration string, e.g. `"60s"`):
+Set a rate limit policy when issuing a key. The policy defines a `quota` (maximum requests) and a `window` (time window as a
+duration string, e.g. `"60s"`):
@@ -38,11 +37,8 @@ RESPONSE=$(talos keys issue "rate-limited-key" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -62,24 +58,19 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')
```
-The response includes the full key metadata with the `rate_limit_policy` attached. For the complete
-request and response field reference, see the
-[IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
+The response includes the full key metadata with the `rate_limit_policy` attached. For the complete request and response field
+reference, see the [IssueAPIKey API reference](../reference/api/admin-issue-api-key.api.mdx).
## Verify a rate-limited key
-Verify the key as you would any other credential. When the key has a rate limit policy, the response
-includes the policy metadata:
+Verify the key as you would any other credential. When the key has a rate limit policy, the response includes the policy metadata:
@@ -100,16 +91,14 @@ curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
-When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining`
-(approximate requests available before the limit is reached) and `rate_limit_reset_time` (when full
-capacity is recovered). For the complete response field reference, see the
-[VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
+When rate limiting is enabled (Commercial), the response also includes `rate_limit_remaining` (approximate requests available
+before the limit is reached) and `rate_limit_reset_time` (when full capacity is recovered). For the complete response field
+reference, see the [VerifyAPIKey API reference](../reference/api/admin-verify-api-key.api.mdx).
## Exceeding the limit
-When a key's quota is exhausted, verification returns `is_active: false` with error code
-`VERIFICATION_ERROR_RATE_LIMITED` (Commercial edition). The response body includes the error code
-and a human-readable message:
+When a key's quota is exhausted, verification returns `is_active: false` with error code `VERIFICATION_ERROR_RATE_LIMITED`
+(Commercial edition). The response body includes the error code and a human-readable message:
```json
{
@@ -119,17 +108,15 @@ and a human-readable message:
}
```
-The HTTP response also includes a `Retry-After` header indicating how many seconds the client should
-wait before retrying. In the OSS edition, enforcement is external -- Talos always returns the policy
-metadata but does not reject requests based on quota.
+The HTTP response also includes a `Retry-After` header indicating how many seconds the client should wait before retrying. In the
+OSS edition, enforcement is external -- Talos always returns the policy metadata but does not reject requests based on quota.
For the complete list of verification error codes, see the
[error codes reference](../reference/error-codes.md#verification-error-codes).
## Update rate limit policy
-Use `PATCH` to change a key's rate limit policy without rotating the secret. Include
-`rate_limit_policy` in the `update_mask`:
+Use `PATCH` to change a key's rate limit policy without rotating the secret. Include `rate_limit_policy` in the `update_mask`:
@@ -159,9 +146,8 @@ curl -s -X PATCH "$TALOS_URL/v2alpha1/admin/issuedApiKeys/$KEY_ID" \
-The updated policy takes effect on the next verification request (subject to cache TTL). For the
-complete update field reference, see the
-[UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
+The updated policy takes effect on the next verification request (subject to cache TTL). For the complete update field reference,
+see the [UpdateIssuedAPIKey API reference](../reference/api/admin-update-issued-api-key.api.mdx).
## Remove rate limit policy
@@ -196,8 +182,7 @@ Once removed, the key is no longer subject to rate limiting.
## HTTP response headers
-When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in
-verification responses:
+When a key has a rate limit policy, the HTTP gateway includes IETF draft-compliant headers in verification responses:
| Header | When present | Description |
| ------------------ | -------------------- | -------------------------------------------------- |
@@ -205,25 +190,22 @@ verification responses:
| `RateLimit` | Always (with policy) | Current state: `limit=100, remaining=42, reset=18` |
| `Retry-After` | Only when limited | Seconds to wait before the next allowed request |
-These headers are present in both editions. In the OSS edition, your API gateway can read them to
-apply enforcement. In the Commercial edition, clients can use them for backoff and retry logic.
+These headers are present in both editions. In the OSS edition, your API gateway can read them to apply enforcement. In the
+Commercial edition, clients can use them for backoff and retry logic.
## Behavior notes
-- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is
- down), verification succeeds but rate limit metadata is omitted. Limiter failures never block
- legitimate traffic.
-- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result
- is served from cache, the rate limiter is not consulted. This means cached responses do not
- decrement the counter.
-- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets,
- even if they belong to the same actor.
-- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate
- effect, use the `Cache-Control: no-cache` header on verification requests.
+- **Fail-open on limiter errors** -- if the rate limiter backend is unavailable (e.g., Redis is down), verification succeeds but
+ rate limit metadata is omitted. Limiter failures never block legitimate traffic.
+- **Cache interaction** -- rate limit checks happen after cache resolution. If a verification result is served from cache, the
+ rate limiter is not consulted. This means cached responses do not decrement the counter.
+- **Per-key isolation** -- each key maintains its own counter. Keys do not share rate limit budgets, even if they belong to the
+ same actor.
+- **Policy changes** -- updated policies take effect on the next cache miss. To force immediate effect, use the
+ `Cache-Control: no-cache` header on verification requests.
## Next steps
-- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs.
- Commercial
-- [Key lifecycle](./key-lifecycle.md) -- update, rotate, and revoke keys
-- [Error handling](./error-handling.md) -- error response format and retry logic
+- [Rate limiting concepts](../concepts/rate-limiting.md) -- how enforcement works in OSS vs. Commercial
+- [Key lifecycle](./key-lifecycle.mdx) -- update, rotate, and revoke keys
+- [Error handling](./error-handling.mdx) -- error response format and retry logic
diff --git a/docs/talos/integrate/sdk/curl.md b/docs/talos/integrate/sdk/curl.md
index 8501ecd8d4..6ab83e204e 100644
--- a/docs/talos/integrate/sdk/curl.md
+++ b/docs/talos/integrate/sdk/curl.md
@@ -29,11 +29,8 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
### Get a key
@@ -77,8 +74,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys/${KEY_ID}:ro
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
```
## Admin plane — Imported keys
@@ -99,8 +95,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.imported_api_key.key_id')
```
### Batch import
@@ -161,8 +156,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
echo "$RESPONSE" | jq .
-JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+export JWT_TOKEN=$(echo "$RESPONSE" | jq -er '.token.token')
```
### Derive a macaroon token
@@ -247,7 +241,7 @@ SELF_REVOKE_RESP=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
-H "Content-Type: application/json" \
-d '{"name":"self-revoke-demo","actor_id":"user_123"}')
-SELF_REVOKE_SECRET=$(echo "$SELF_REVOKE_RESP" | jq -r '.secret')
+SELF_REVOKE_SECRET=$(echo "$SELF_REVOKE_RESP" | jq -er '.secret')
curl -s -X POST "$TALOS_URL/v2alpha1/apiKeys:selfRevoke" \
-H "Content-Type: application/json" \
diff --git a/docs/talos/integrate/sdk/go.md b/docs/talos/integrate/sdk/go.md
index 12802a7180..830a0436a4 100644
--- a/docs/talos/integrate/sdk/go.md
+++ b/docs/talos/integrate/sdk/go.md
@@ -5,15 +5,14 @@ description: Using the generated Go HTTP client
# Go SDK
-Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is
-generated using `openapi-generator` and lives in the `internal/client/generated` package.
+Talos provides a generated Go HTTP client based on the OpenAPI specification. The client is generated using `openapi-generator`
+and lives in the `internal/client/generated` package.
:::note
-Internal package: the Go client is in an `internal/` package and cannot be imported by external Go
-modules. It is used for Talos's own integration tests and the admin UI backend. If you need a Go
-client for your application, generate one from the OpenAPI spec at `api/talos.openapi-v2.json`
-using [OpenAPI Generator](https://openapi-generator.tech/).
+Internal package: the Go client is in an `internal/` package and cannot be imported by external Go modules. It is used for Talos's
+own integration tests and the admin UI backend. If you need a Go client for your application, generate one from the OpenAPI spec
+at `api/talos.openapi-v3.json` using [OpenAPI Generator](https://openapi-generator.tech/).
:::
@@ -24,19 +23,18 @@ using [OpenAPI Generator](https://openapi-generator.tech/).
```bash
openapi-generator generate \
- -i api/talos.openapi-v2.json \
+ -i api/talos.openapi-v3.json \
-g go \
-o generated/go-client
```
-The examples below use the internal client's types for illustration. A generated external client has
-the same API shape.
+The examples below use the internal client's types for illustration. A generated external client has the same API shape.
:::tip
Full working example: see
-[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go)
-for a complete, runnable program that exercises all operations shown below.
+[`tools/doctest/examples/go_sdk/main.go`](https://github.com/ory-corp/talos/blob/dev/tools/doctest/examples/go_sdk/main.go) for a
+complete, runnable program that exercises all operations shown below.
:::
@@ -174,9 +172,8 @@ fmt.Println("JWT:", derivedToken.GetToken())
## Error handling
The SDK returns an error for every non-2xx response. The error wraps a
-[`google.rpc.Status`](https://cloud.google.com/apis/design/errors#error_model) body — read it via
-the typed `GenericOpenAPIError`, not the HTTP response, so you get the canonical gRPC code,
-human-readable message, and any `ErrorInfo` details.
+[`google.rpc.Status`](https://cloud.google.com/apis/design/errors#error_model) body — read it via the typed `GenericOpenAPIError`,
+not the HTTP response, so you get the canonical gRPC code, human-readable message, and any `ErrorInfo` details.
@@ -211,12 +208,11 @@ if err != nil {
}
```
-Match on `details[*].reason` from the `ErrorInfo` detail — it is the stable, machine-readable
-identifier. The `message` field is meant for logs and can change between releases.
+Match on `details[*].reason` from the `ErrorInfo` detail — it is the stable, machine-readable identifier. The `message` field is
+meant for logs and can change between releases.
-For the verify endpoint, a verification failure returns `200 OK` with `is_active: false`, not an
-HTTP error. Branch on `verifyResp.GetIsActive()` and inspect `verifyResp.GetErrorCode()` instead of
-treating it as an SDK error.
+For the verify endpoint, a verification failure returns `200 OK` with `is_active: false`, not an HTTP error. Branch on
+`verifyResp.GetIsActive()` and inspect `verifyResp.GetErrorCode()` instead of treating it as an SDK error.
## Regenerating the client
@@ -226,5 +222,4 @@ The Go SDK is regenerated with:
make generate-sdk
```
-This reads the OpenAPI spec from `api/talos.openapi-v2.json` and outputs to
-`internal/client/generated/`.
+This reads the OpenAPI spec from `api/talos.openapi-v3.json` and outputs to `internal/client/generated/`.
diff --git a/docs/talos/integrate/self-revocation.md b/docs/talos/integrate/self-revocation.mdx
similarity index 70%
rename from docs/talos/integrate/self-revocation.md
rename to docs/talos/integrate/self-revocation.mdx
index 69ae583f81..495750ed1e 100644
--- a/docs/talos/integrate/self-revocation.md
+++ b/docs/talos/integrate/self-revocation.mdx
@@ -3,16 +3,17 @@ title: Self-revocation
description: Allow API key holders to revoke their own keys
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Self-revocation
-The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the
-secret. This is a data plane operation — it does not require admin access.
+The self-revoke endpoint lets an API key holder revoke their own key by proving possession of the secret. This is a data plane
+operation — it does not require admin access.
## Prerequisites
-A running Talos server. See the [quickstart](../quickstart/index.md) to start one locally.
+A running Talos server. See the [quickstart](../quickstart/index.mdx) to start one locally.
@@ -33,12 +34,11 @@ First, issue a key to get a secret:
```bash
-SELF_REVOKE_SECRET=$(talos keys issue "self-revoke-demo" \
+export SELF_REVOKE_SECRET=$(talos keys issue "self-revoke-demo" \
--actor user_99 \
--scopes "read:data" \
--format json \
- -e "$TALOS_URL" 2>/dev/null | jq -r '.secret')
-echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
+ -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')
```
@@ -53,8 +53,7 @@ ISSUE_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
"scopes": ["read:data"]
}')
-SELF_REVOKE_SECRET=$(echo "$ISSUE_RESPONSE" | jq -r '.secret')
-echo "export SELF_REVOKE_SECRET=$SELF_REVOKE_SECRET" >> "$DOCTEST_ENV_FILE"
+export SELF_REVOKE_SECRET=$(echo "$ISSUE_RESPONSE" | jq -er '.secret')
```
@@ -124,29 +123,26 @@ fi
-The request requires `credential` (the full API key secret) and optionally `reason` (revocation
-reason enum). For the complete field reference, see the
-[SelfRevokeAPIKey API reference](../reference/api/revoke-api-key.api.mdx).
+The request requires `credential` (the full API key secret) and optionally `reason` (revocation reason enum). For the complete
+field reference, see the [SelfRevokeAPIKey API reference](../reference/api/revoke-api-key.api.mdx).
-Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are
-stateless and cannot be revoked. All revocation reasons except
-`REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
+Only issued and imported API keys can be self-revoked. Derived tokens (JWTs and macaroons) are stateless and cannot be revoked.
+All revocation reasons except `REVOCATION_REASON_PRIVILEGE_WITHDRAWN` are allowed — that reason is reserved for admin-initiated
revocations.
-A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is
-immediately revoked.
+A successful self-revocation returns an empty response with HTTP status `200 OK`. The key is immediately revoked.
## Admin vs self-revocation
-| | Admin revocation | Self-revocation |
-| --------------------- | ---------------------------------------- | -------------------------------- |
-| Endpoint | `POST /v2alpha1/admin/apiKeys/{key_id}:revoke` | `POST /v2alpha1/apiKeys:selfRevoke` |
-| Plane | Admin | Data |
-| Authentication | Requires admin access | Proof of possession (key secret) |
-| Identifier | Key ID | Key secret |
-| `PRIVILEGE_WITHDRAWN` | Allowed | Not allowed |
+| | Admin revocation | Self-revocation |
+| --------------------- | ---------------------------------------------- | ----------------------------------- |
+| Endpoint | `POST /v2alpha1/admin/apiKeys/{key_id}:revoke` | `POST /v2alpha1/apiKeys:selfRevoke` |
+| Plane | Admin | Data |
+| Authentication | Requires admin access | Proof of possession (key secret) |
+| Identifier | Key ID | Key secret |
+| `PRIVILEGE_WITHDRAWN` | Allowed | Not allowed |
## Next steps
-- [Key lifecycle](key-lifecycle.md) — admin-side key management
-- [Error handling](error-handling.md) — handle revocation errors
+- [Key lifecycle](key-lifecycle.mdx) — admin-side key management
+- [Error handling](error-handling.mdx) — handle revocation errors
diff --git a/docs/talos/operate/benchmarks.md b/docs/talos/operate/benchmarks.md
index 68470f42e7..ed8ee014ce 100644
--- a/docs/talos/operate/benchmarks.md
+++ b/docs/talos/operate/benchmarks.md
@@ -5,21 +5,20 @@ description: Performance benchmarks and load testing for Ory Talos
# Benchmarks
-Talos includes a k6-based load test suite that measures throughput, latency, and correctness under
-concurrent load. Use these benchmarks to validate your deployment and catch performance regressions.
+Talos includes a k6-based load test suite that measures throughput, latency, and correctness under concurrent load. Use these
+benchmarks to validate your deployment and catch performance regressions.
:::note
-These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS
-edition uses SQLite, which does not support concurrent writers and cannot handle the parallel load
-generated by multi-VU test profiles.
+These benchmarks require the **Commercial edition** with PostgreSQL (or CockroachDB/MySQL). The OSS edition uses SQLite, which
+does not support concurrent writers and cannot handle the parallel load generated by multi-VU test profiles.
:::
## Reference results
-Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress
-profile (ramping 0→437 VUs over 5 minutes):
+Measured on Apple M-series (M4 Pro Max), single-process commercial binary with PostgreSQL 16, stress profile (ramping 0→437 VUs
+over 5 minutes):
| Metric | Value |
| ------------------- | ------------ |
@@ -52,8 +51,8 @@ The stress profile ramps through four stages:
4. **Hold**: 150 VUs for 120s
5. **Ramp down**: 150→0 VUs over 30s
-Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write
-scenarios (create, rotate, revoke, import, update, self-revoke) get ~30%.
+Read scenarios (verify, batch verify, get key, list keys, JWKS, derive token) get ~70% of VUs. Write scenarios (create, rotate,
+revoke, import, update, self-revoke) get ~30%.
## Running benchmarks
@@ -76,8 +75,8 @@ TEST_PROFILE=load bash test/load/run.sh
TEST_PROFILE=stress bash test/load/run.sh
```
-The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker,
-runs migrations, seeds tenant data, starts the server, and executes k6.
+The `run.sh` script handles everything: builds the commercial binary, starts PostgreSQL in Docker, runs migrations, seeds tenant
+data, starts the server, and executes k6.
### Using an existing database
@@ -125,12 +124,10 @@ Each profile enforces regression thresholds. Tests fail if any threshold is brea
After a k6 run, look for:
- **`checks` rate**: Must be 100%. Any failure indicates a correctness bug.
-- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases
- suggest a regression.
+- **`http_req_duration` percentiles**: Compare against the thresholds above. Significant increases suggest a regression.
- **`http_req_failed` rate**: Should be 0% for smoke/load. Under 1% for stress.
-- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against
- the reference results to detect throughput regressions.
+- **Custom counters** (`key_creations`, `verifications`, `token_derivations`): Compare rates against the reference results to
+ detect throughput regressions.
- **`iteration_duration`**: End-to-end time for each VU iteration including all operations.
-Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json`
-(machine-readable).
+Results are saved to `.test/k6-output.txt` (human-readable) and `.test/k6-results.json` (machine-readable).
diff --git a/docs/talos/operate/cache/index.md b/docs/talos/operate/cache/index.md
index e5037c98be..10760e2546 100644
--- a/docs/talos/operate/cache/index.md
+++ b/docs/talos/operate/cache/index.md
@@ -24,8 +24,8 @@ cache:
## Consistency
-Caching introduces eventual consistency. A revoked key may continue to pass verification until the
-cache entry expires (default: 5 minutes).
+Caching introduces eventual consistency. A revoked key may continue to pass verification until the cache entry expires (default: 5
+minutes).
-**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for
-individual requests when immediate consistency is required.
+**Bypass cache:** Use `Cache-Control: no-cache` on verification requests to bypass the cache for individual requests when
+immediate consistency is required.
diff --git a/docs/talos/operate/cache/memory.md b/docs/talos/operate/cache/memory.md
index 2f08db13e9..1fba0276b4 100644
--- a/docs/talos/operate/cache/memory.md
+++ b/docs/talos/operate/cache/memory.md
@@ -7,8 +7,7 @@ sidebar_custom_props:
# In-memory cache
-The in-memory cache stores verification results in the Talos process using a ristretto-based LRU
-cache.
+The in-memory cache stores verification results in the Talos process using a ristretto-based LRU cache.
## Configuration
@@ -30,6 +29,5 @@ cache:
## When to use
-Use the in-memory cache for single-node deployments or when each Talos instance handles enough
-traffic to benefit from local caching. For multi-instance deployments, consider [Redis](redis.md)
-for shared cache across all instances.
+Use the in-memory cache for single-node deployments or when each Talos instance handles enough traffic to benefit from local
+caching. For multi-instance deployments, consider [Redis](redis.md) for shared cache across all instances.
diff --git a/docs/talos/operate/cache/redis.md b/docs/talos/operate/cache/redis.md
index 8779a8eba3..7f9d7b26f9 100644
--- a/docs/talos/operate/cache/redis.md
+++ b/docs/talos/operate/cache/redis.md
@@ -30,20 +30,20 @@ cache:
## Parameters
-| Parameter | Default | Range / format | Description |
-| -------------------- | -------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
-| `addrs` | `["localhost:6379"]` | One or more `host:port` entries | Redis server addresses. Multiple entries enable cluster or sentinel topologies. |
-| `password` | — | Any string | Redis password. Leave empty for unauthenticated Redis. |
-| `db` | `0` | `0`–`15` | Logical Redis database. Cluster mode only supports `0`. |
-| `pool_size` | `100` | `1`–`1000` | Maximum number of connections per address. |
-| `min_idle_conns` | `2` | `≥ 0` | Minimum idle connections kept open per address. Reduces cold-start latency. |
-| `conn_max_idle_time` | `5m` | Go duration string | Maximum time a connection can sit idle before being closed. |
-| `conn_max_lifetime` | `30m` | Go duration string | Maximum time a connection can be reused before being recycled. |
-| `timeout` | `3s` | Go duration string | Timeout for individual Redis operations (`GET`, `SET`, etc.). |
-| `tls.enabled` | `false` | Boolean | Enable TLS using the system certificate pool. Required for TLS-only Redis. |
-
-All Redis parameters are immutable: changing them requires a server restart. Only `pool_size` and
-`timeout` can be tuned without restart.
+| Parameter | Default | Range / format | Description |
+| -------------------- | -------------------- | ------------------------------- | ------------------------------------------------------------------------------- |
+| `addrs` | `["localhost:6379"]` | One or more `host:port` entries | Redis server addresses. Multiple entries enable cluster or sentinel topologies. |
+| `password` | — | Any string | Redis password. Leave empty for unauthenticated Redis. |
+| `db` | `0` | `0`–`15` | Logical Redis database. Cluster mode only supports `0`. |
+| `pool_size` | `100` | `1`–`1000` | Maximum number of connections per address. |
+| `min_idle_conns` | `2` | `≥ 0` | Minimum idle connections kept open per address. Reduces cold-start latency. |
+| `conn_max_idle_time` | `5m` | Go duration string | Maximum time a connection can sit idle before being closed. |
+| `conn_max_lifetime` | `30m` | Go duration string | Maximum time a connection can be reused before being recycled. |
+| `timeout` | `3s` | Go duration string | Timeout for individual Redis operations (`GET`, `SET`, etc.). |
+| `tls.enabled` | `false` | Boolean | Enable TLS using the system certificate pool. Required for TLS-only Redis. |
+
+All Redis parameters are immutable: changing them requires a server restart. Only `pool_size` and `timeout` can be tuned without
+restart.
## Cluster and sentinel topologies
@@ -67,26 +67,24 @@ In cluster mode, `db` must be `0` — Redis Cluster does not support multiple lo
## TLS
-Set `tls.enabled: true` when the Redis endpoint terminates TLS. Talos uses the operating system's
-certificate pool to verify the server certificate. Self-signed or private CA deployments must add
-the CA to the OS trust store on every Talos node — there is no per-process CA bundle option.
+Set `tls.enabled: true` when the Redis endpoint terminates TLS. Talos uses the operating system's certificate pool to verify the
+server certificate. Self-signed or private CA deployments must add the CA to the OS trust store on every Talos node — there is no
+per-process CA bundle option.
## Connection pool sizing
-The defaults (`pool_size: 100`, `min_idle_conns: 2`, `conn_max_lifetime: 30m`) suit most
-deployments. Tune them only when you can show a problem:
+The defaults (`pool_size: 100`, `min_idle_conns: 2`, `conn_max_lifetime: 30m`) suit most deployments. Tune them only when you can
+show a problem:
-- **Saturated pool:** if `redis_pool_wait_seconds` (when exposed by your client metrics) is
- consistently non-zero, increase `pool_size`.
-- **Connection churn:** if Redis logs show frequent connect/disconnect from Talos, increase
- `min_idle_conns`.
+- **Saturated pool:** if `redis_pool_wait_seconds` (when exposed by your client metrics) is consistently non-zero, increase
+ `pool_size`.
+- **Connection churn:** if Redis logs show frequent connect/disconnect from Talos, increase `min_idle_conns`.
- **Stale connections after failover:** lower `conn_max_lifetime` to force quicker rotation.
-Do not set `pool_size` above your Redis server's `maxclients` divided by the number of Talos
-instances — running out of Redis connections fails open with a cache miss but spams logs.
+Do not set `pool_size` above your Redis server's `maxclients` divided by the number of Talos instances — running out of Redis
+connections fails open with a cache miss but spams logs.
## When to use
-Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances,
-reducing database load. Redis is also required for [edge proxy](../deploy/edge-proxy.md) deployments
-where each edge node shares a regional Redis instance.
+Use Redis when running multiple Talos instances. A cache hit on one instance benefits all instances, reducing database load. Redis
+is also required for [edge proxy](../deploy/edge-proxy.md) deployments where each edge node shares a regional Redis instance.
diff --git a/docs/talos/operate/configure.md b/docs/talos/operate/configure.md
index ae59f7c090..b5a877cb39 100644
--- a/docs/talos/operate/configure.md
+++ b/docs/talos/operate/configure.md
@@ -5,15 +5,13 @@ description: Configuration reference for Ory Talos
# Configure
-Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set
-through environment variables or CLI flags. See the
-[Configuration reference](../reference/config.md) for the complete list of keys, types, defaults,
+Talos is configured through a YAML file passed via the `--config` flag. All settings can also be set through environment variables
+or CLI flags. See the [Configuration reference](../reference/config.mdx) for the complete list of keys, types, defaults,
environment variable mappings, and precedence rules.
## Hot-reload
-Talos watches the config file for changes. Some settings reload automatically, others require a
-restart.
+Talos watches the config file for changes. Some settings reload automatically, others require a restart.
**Hot-reloadable:**
@@ -35,8 +33,8 @@ restart.
## Duration syntax
-All duration values (TTLs, timeouts, intervals) are Go duration strings. Combine one or more
-unsigned numbers with a unit, no spaces. Supported units:
+All duration values (TTLs, timeouts, intervals) are Go duration strings. Combine one or more unsigned numbers with a unit, no
+spaces. Supported units:
| Unit | Meaning |
| ---- | ------------ |
@@ -48,8 +46,8 @@ unsigned numbers with a unit, no spaces. Supported units:
| `m` | minutes |
| `h` | hours |
-Examples: `500ms`, `30s`, `5m`, `1h30m`, `8760h` (one year). Days, weeks, months, and years are
-**not** supported — express them in hours (`24h`, `168h`, `8760h`).
+Examples: `500ms`, `30s`, `5m`, `1h30m`, `8760h` (one year). Days, weeks, months, and years are **not** supported — express them
+in hours (`24h`, `168h`, `8760h`).
## Minimal configuration
@@ -128,5 +126,5 @@ tracing: # Commercial only
sample_rate: 0.01
```
-See the [Configuration reference](../reference/config.md) for all available keys with types,
-defaults, and environment variable mappings.
+See the [Configuration reference](../reference/config.mdx) for all available keys with types, defaults, and environment variable
+mappings.
diff --git a/docs/talos/operate/database/cockroachdb.md b/docs/talos/operate/database/cockroachdb.md
index 18453ab751..9b93f12351 100644
--- a/docs/talos/operate/database/cockroachdb.md
+++ b/docs/talos/operate/database/cockroachdb.md
@@ -32,32 +32,27 @@ export TALOS_DB_DSN="cockroach://talos@crdb:26257/talos?sslmode=verify-full&max_
cockroach://user:password@host:port/dbname?param=value¶m=value
```
-Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted
-to `postgres://` since CockroachDB uses the PostgreSQL wire protocol.
+Both `cockroach://` and `cockroachdb://` schemes are accepted. Internally, the scheme is converted to `postgres://` since
+CockroachDB uses the PostgreSQL wire protocol.
## DSN parameters, connection pooling, and TLS
-CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including
-both standard and advanced pool modes. For the full parameter reference, see the
-[PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
-[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl)
-documentation.
+CockroachDB uses the PostgreSQL `pgx` driver and shares the same pooling infrastructure, including both standard and advanced pool
+modes. For the full parameter reference, see the [PostgreSQL DSN parameters](postgresql.md#dsn-parameters),
+[connection pooling](postgresql.md#connection-pooling), and [TLS / SSL](postgresql.md#tls--ssl) documentation.
Key differences from PostgreSQL:
-- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of
- `25`.
+- **Higher pool sizes** — CockroachDB connections are lighter. Start with `max_conns=50` instead of `25`.
- **Per-node connection limits still apply** — each CockroachDB node enforces its own
- `sql.defaults.idle_in_transaction_session_timeout` and accepts a finite number of connections.
- Aim for the sum of every Talos pool that targets a node to stay below that node's limit. You
- rarely need PgBouncer in front of CockroachDB, but the limit is per-node, not global.
-- **Schema-change blast radius** — CockroachDB applies online schema changes asynchronously.
- Always run `talos migrate up` from a single instance, then wait for the schema-change job to
- finish (`SHOW JOBS WHEN status = 'running'`) before starting a rolling deploy of the new
- application version.
-- **Rollback path** — `talos migrate down` is supported but irreversible if the previous version
- has already written data using the new schema. For destructive migrations, take a backup
- (`BACKUP INTO …`) before applying.
+ `sql.defaults.idle_in_transaction_session_timeout` and accepts a finite number of connections. Aim for the sum of every Talos
+ pool that targets a node to stay below that node's limit. You rarely need PgBouncer in front of CockroachDB, but the limit is
+ per-node, not global.
+- **Schema-change blast radius** — CockroachDB applies online schema changes asynchronously. Always run `talos migrate up` from a
+ single instance, then wait for the schema-change job to finish (`SHOW JOBS WHEN status = 'running'`) before starting a rolling
+ deploy of the new application version.
+- **Rollback path** — `talos migrate down` is supported but irreversible if the previous version has already written data using
+ the new schema. For destructive migrations, take a backup (`BACKUP INTO …`) before applying.
## Migrations
@@ -67,9 +62,8 @@ talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
## Multi-region
-Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification
-latency. Talos does not require special configuration beyond pointing `db.dsn` at the local
-CockroachDB node.
+Deploy Talos data plane nodes in each region alongside CockroachDB nodes to minimize verification latency. Talos does not require
+special configuration beyond pointing `db.dsn` at the local CockroachDB node.
```yaml
# Region: us-east-1
@@ -83,8 +77,7 @@ db:
## Performance
-CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For
-verification-heavy workloads:
+CockroachDB has higher write latency than PostgreSQL due to distributed consensus (Raft). For verification-heavy workloads:
- Enable [caching](../cache/index.md) to absorb verification reads
- Use `max_conns=50` or higher — CockroachDB connections are lighter than PostgreSQL
diff --git a/docs/talos/operate/database/index.md b/docs/talos/operate/database/index.md
index 163f881cc3..9c520783f8 100644
--- a/docs/talos/operate/database/index.md
+++ b/docs/talos/operate/database/index.md
@@ -4,8 +4,7 @@ title: Database
# Database
-Talos stores API key data in a relational database. The backend is determined by the DSN scheme in
-`db.dsn`.
+Talos stores API key data in a relational database. The backend is determined by the DSN scheme in `db.dsn`.
## Supported backends
diff --git a/docs/talos/operate/database/migrations.md b/docs/talos/operate/database/migrations.md
index 8c6fbab193..2654ef713f 100644
--- a/docs/talos/operate/database/migrations.md
+++ b/docs/talos/operate/database/migrations.md
@@ -27,32 +27,27 @@ talos migrate force 17 --database "sqlite:///var/lib/talos/data.db"
## Upgrade workflow
-1. **Back up the database.** For PostgreSQL or CockroachDB, take a logical backup with `pg_dump`
- or `BACKUP INTO`; for MySQL, use `mysqldump`. SQLite users can simply copy the file.
-2. **Drain admin traffic.** Run `talos migrate up` from a single instance — concurrent migration
- runners race against each other and can leave the schema dirty.
-3. **Apply migrations.** Run `talos migrate up`. Watch stderr; the command exits non-zero on
- failure.
-4. **Resolve dirty state if needed.** If migration fails partway through, `migrate up` and
- `migrate down` will refuse to run with `Error: Database is in dirty state at version N`.
- Inspect the schema, complete or revert the partial change manually, then run
- `talos migrate force ` to mark the migration tracker. Never rerun on top of a dirty
- state.
-5. **Verify with `talos migrate status`.** Confirm the version matches the new binary's expected
- schema and that `STATUS` reports `OK`, not `DIRTY`.
-6. **Roll the application.** Start replicas of the new binary in a rolling deploy. Old replicas
- continue serving against the new schema until they are replaced.
+1. **Back up the database.** For PostgreSQL or CockroachDB, take a logical backup with `pg_dump` or `BACKUP INTO`; for MySQL, use
+ `mysqldump`. SQLite users can simply copy the file.
+2. **Drain admin traffic.** Run `talos migrate up` from a single instance — concurrent migration runners race against each other
+ and can leave the schema dirty.
+3. **Apply migrations.** Run `talos migrate up`. Watch stderr; the command exits non-zero on failure.
+4. **Resolve dirty state if needed.** If migration fails partway through, `migrate up` and `migrate down` will refuse to run with
+ `Error: Database is in dirty state at version N`. Inspect the schema, complete or revert the partial change manually, then run
+ `talos migrate force ` to mark the migration tracker. Never rerun on top of a dirty state.
+5. **Verify with `talos migrate status`.** Confirm the version matches the new binary's expected schema and that `STATUS` reports
+ `OK`, not `DIRTY`.
+6. **Roll the application.** Start replicas of the new binary in a rolling deploy. Old replicas continue serving against the new
+ schema until they are replaced.
## Production safety
-- Run `talos migrate up` from a Job, init container, or operator — never from inside the
- application's startup path. Concurrent migration runners can deadlock or corrupt the migration
- tracker.
-- Pin the migration image to the same version as the application image. Do not use mutable tags
- (`latest`, `staging`) for migration jobs.
-- Talos commercial migrations live under `commercial/persistence/migrations/{postgres,mysql,cockroach}/`;
- the OSS image only ships SQLite migrations and cannot apply them. Use the
- `oryd/talos-commercial` image for PostgreSQL, MySQL, and CockroachDB.
+- Run `talos migrate up` from a Job, init container, or operator — never from inside the application's startup path. Concurrent
+ migration runners can deadlock or corrupt the migration tracker.
+- Pin the migration image to the same version as the application image. Do not use mutable tags (`latest`, `staging`) for
+ migration jobs.
+- Talos commercial migrations live under `commercial/persistence/migrations/{postgres,mysql,cockroach}/`; the OSS image only ships
+ SQLite migrations and cannot apply them. Use the `oryd/talos-commercial` image for PostgreSQL, MySQL, and CockroachDB.
## DSN examples
@@ -72,9 +67,8 @@ talos-commercial migrate up --database "cockroach://talos@crdb:26257/talos"
## Kubernetes
-Use a Job to apply migrations once, then start the application Deployment. The OSS image
-(`oryd/talos:latest`) only ships SQLite migrations; for PostgreSQL, MySQL, or CockroachDB use
-`oryd/talos-commercial:latest`.
+Use a Job to apply migrations once, then start the application Deployment. The OSS image (`oryd/talos:latest`) only ships SQLite
+migrations; for PostgreSQL, MySQL, or CockroachDB use `oryd/talos-commercial:latest`.
```yaml
apiVersion: batch/v1
@@ -82,12 +76,12 @@ kind: Job
metadata:
name: talos-migrate
spec:
- backoffLimit: 0 # Do not retry — a failed migration leaves the schema dirty.
+ backoffLimit: 0 # Do not retry — a failed migration leaves the schema dirty.
template:
spec:
containers:
- name: migrate
- image: oryd/talos-commercial:latest # Pin to the same tag as the application image.
+ image: oryd/talos-commercial:latest # Pin to the same tag as the application image.
command: ["talos", "migrate", "up"]
env:
- name: TALOS_DB_DSN
diff --git a/docs/talos/operate/database/mysql.md b/docs/talos/operate/database/mysql.md
index 7a4f0b7ed3..561cb39307 100644
--- a/docs/talos/operate/database/mysql.md
+++ b/docs/talos/operate/database/mysql.md
@@ -32,13 +32,13 @@ export TALOS_DB_DSN="mysql://talos:secret@tcp(db:3306)/talos?tls=true&parseTime=
mysql://user:password@tcp(host:port)/dbname?param=value¶m=value
```
-The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before
-passing the DSN to the Go MySQL driver.
+The `mysql://` scheme prefix is required in the configuration. Talos strips it internally before passing the DSN to the Go MySQL
+driver.
:::caution
-Required parameter: always include `parseTime=true` in the DSN. Without it, datetime columns are
-returned as byte arrays instead of `time.Time`, causing runtime errors.
+Required parameter: always include `parseTime=true` in the DSN. Without it, datetime columns are returned as byte arrays instead
+of `time.Time`, causing runtime errors.
:::
@@ -46,8 +46,7 @@ returned as byte arrays instead of `time.Time`, causing runtime errors.
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
-database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
| Parameter | Type | Default | Description |
| -------------------- | -------- | ------- | ------------------------------------------------------------ |
@@ -58,9 +57,8 @@ database driver.
Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
-Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are
-recycled through load balancers and DNS rotation. Setting either to `0` disables the recycle and
-is **not recommended** outside development.
+Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are recycled through load balancers
+and DNS rotation. Setting either to `0` disables the recycle and is **not recommended** outside development.
MySQL uses standard `database/sql` pooling only. There is no advanced pool mode.
@@ -98,8 +96,8 @@ Pool behavior:
### Pool sizing
-Start with 25 connections per instance. The total pool across all instances should stay below
-MySQL's `max_connections` (default: 151).
+Start with 25 connections per instance. The total pool across all instances should stay below MySQL's `max_connections` (default:
+151).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -107,9 +105,8 @@ MySQL's `max_connections` (default: 151).
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use ProxySQL or MySQL Router to multiplex |
-For large deployments, place [ProxySQL](https://proxysql.com/) or
-[MySQL Router](https://dev.mysql.com/doc/mysql-router/en/) between Talos and MySQL for connection
-multiplexing.
+For large deployments, place [ProxySQL](https://proxysql.com/) or [MySQL Router](https://dev.mysql.com/doc/mysql-router/en/)
+between Talos and MySQL for connection multiplexing.
## Database preparation
diff --git a/docs/talos/operate/database/postgresql.md b/docs/talos/operate/database/postgresql.md
index 26c7837dcb..ddb54fdbb5 100644
--- a/docs/talos/operate/database/postgresql.md
+++ b/docs/talos/operate/database/postgresql.md
@@ -7,8 +7,8 @@ sidebar_custom_props:
# PostgreSQL
-PostgreSQL is the recommended production database backend. It provides connection pooling, ACID
-transactions, and high-availability via streaming replication.
+PostgreSQL is the recommended production database backend. It provides connection pooling, ACID transactions, and
+high-availability via streaming replication.
## Supported versions
@@ -39,22 +39,21 @@ Both `postgres://` and `postgresql://` schemes are accepted.
### Connection pool parameters
-Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the
-database driver.
+Pool parameters are parsed from the DSN query string and removed before the DSN is passed to the database driver.
-| Parameter | Type | Default | Description |
-| -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------ |
-| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
-| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
-| `max_conn_lifetime` | duration | `30m` | Maximum age of a connection before it is closed and replaced |
-| `max_conn_idle_time` | duration | `10m` | Maximum time a connection can sit idle before it is closed |
-| `pool_mode` | string | `standard` | Pool implementation: `standard` or `advanced` (see below) |
+| Parameter | Type | Default | Description |
+| -------------------- | -------- | ---------- | ------------------------------------------------------------ |
+| `max_conns` | integer | `25` | Maximum number of open connections in the pool |
+| `max_idle_conns` | integer | `5` | Maximum number of idle connections (must be ≤ `max_conns`) |
+| `max_conn_lifetime` | duration | `30m` | Maximum age of a connection before it is closed and replaced |
+| `max_conn_idle_time` | duration | `10m` | Maximum time a connection can sit idle before it is closed |
+| `pool_mode` | string | `standard` | Pool implementation: `standard` or `advanced` (see below) |
Duration values use Go duration syntax: `5m` (5 minutes), `1h` (1 hour), `30s` (30 seconds).
-Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are
-recycled through load balancers, DNS rotation, and PostgreSQL `tcp_keepalives_*`. Setting either
-to `0` disables the recycle and is **not recommended** outside development.
+Talos sets non-zero defaults for `max_conn_lifetime` and `max_conn_idle_time` so connections are recycled through load balancers,
+DNS rotation, and PostgreSQL `tcp_keepalives_*`. Setting either to `0` disables the recycle and is **not recommended** outside
+development.
### PostgreSQL driver parameters
@@ -75,8 +74,7 @@ Talos supports two pool modes for PostgreSQL, controlled by the `pool_mode` DSN
### Standard mode (default)
-Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with
-all tooling.
+Uses Go's `database/sql` connection pool with the `pgx` driver. This is the default and works with all tooling.
```yaml
db:
@@ -92,29 +90,28 @@ Pool behavior:
### Advanced mode
-Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is
-optimized for Kubernetes and cloud environments.
+Uses native `pgxpool` for high-availability deployments. Provides built-in health checks and is optimized for Kubernetes and cloud
+environments.
```yaml
db:
dsn: "postgres://talos:secret@db:5432/talos?pool_mode=advanced&pool_max_conns=50&pool_min_conns=2&pool_max_conn_lifetime=30m&pool_max_conn_idle_time=10m"
```
-In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the
-DSN. The `max_conns`, `max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters
-are **ignored** — use the `pool_*` equivalents instead.
+In advanced mode, pool sizing is configured through pgxpool's native parameters parsed from the DSN. The `max_conns`,
+`max_idle_conns`, `max_conn_lifetime`, and `max_conn_idle_time` parameters are **ignored** — use the `pool_*` equivalents instead.
-| pgxpool parameter | Default | Description |
-| ------------------------- | ---------------------- | ------------------------------------------------------ |
-| `pool_max_conns` | `4 × runtime.NumCPU()` | Maximum size of the pgxpool connection pool |
-| `pool_min_conns` | `0` | Minimum number of connections kept open |
-| `pool_max_conn_lifetime` | `1h` | Maximum age of a connection before it is replaced |
-| `pool_max_conn_idle_time` | `30m` | Maximum idle time before an idle connection is closed |
-| `pool_health_check_period`| `1m` | Interval between background health checks |
+| pgxpool parameter | Default | Description |
+| -------------------------- | ---------------------- | ----------------------------------------------------- |
+| `pool_max_conns` | `4 × runtime.NumCPU()` | Maximum size of the pgxpool connection pool |
+| `pool_min_conns` | `0` | Minimum number of connections kept open |
+| `pool_max_conn_lifetime` | `1h` | Maximum age of a connection before it is replaced |
+| `pool_max_conn_idle_time` | `30m` | Maximum idle time before an idle connection is closed |
+| `pool_health_check_period` | `1m` | Interval between background health checks |
-Talos exposes the pgxpool through Go's `database/sql` interface. The wrapper's
-`SetMaxIdleConns` is forced to `0` so that `database/sql` never holds connections idle on top of
-pgxpool — the pgxpool layer is the single source of truth for pool sizing in advanced mode.
+Talos exposes the pgxpool through Go's `database/sql` interface. The wrapper's `SetMaxIdleConns` is forced to `0` so that
+`database/sql` never holds connections idle on top of pgxpool — the pgxpool layer is the single source of truth for pool sizing in
+advanced mode.
Use advanced mode when:
@@ -124,8 +121,8 @@ Use advanced mode when:
## Pool sizing
-Start with 25 connections per instance. The total pool across all instances must stay below
-PostgreSQL's `max_connections` (default: 100).
+Start with 25 connections per instance. The total pool across all instances must stay below PostgreSQL's `max_connections`
+(default: 100).
| Deployment | `max_conns` | Notes |
| --------------- | -------------- | ------------------------------------------- |
@@ -133,9 +130,8 @@ PostgreSQL's `max_connections` (default: 100).
| 3 instances | `25` each | 75 total — within default `max_connections` |
| 5+ instances | `15`–`20` each | Use PgBouncer to multiplex connections |
-For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL.
-PgBouncer multiplexes many application connections over fewer database connections, allowing you to
-scale beyond PostgreSQL's connection limit.
+For large deployments, place [PgBouncer](https://www.pgbouncer.org/) between Talos and PostgreSQL. PgBouncer multiplexes many
+application connections over fewer database connections, allowing you to scale beyond PostgreSQL's connection limit.
## Migrations
diff --git a/docs/talos/operate/deploy/edge-proxy.md b/docs/talos/operate/deploy/edge-proxy.md
index 856081afe2..c7121593a9 100644
--- a/docs/talos/operate/deploy/edge-proxy.md
+++ b/docs/talos/operate/deploy/edge-proxy.md
@@ -7,8 +7,7 @@ sidebar_custom_props:
# Edge proxy
-Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification
-latency.
+Deploy a caching reverse proxy as a sidecar to your application for sub-millisecond verification latency.
## Pattern
@@ -39,9 +38,10 @@ graph TB
## How it works
-The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos
-server. It intercepts `POST` requests to `/v2alpha1/verify/*` endpoints, caches positive (active)
-verification responses locally, and proxies everything else to upstream unchanged.
+The edge proxy is an HTTP reverse proxy that sits between your application and a central Talos server. It intercepts `POST`
+requests to `/v2alpha1/admin/apiKeys:verify`, caches positive (active) verification responses locally, and proxies everything else
+to upstream unchanged. Verify is an admin endpoint, so the proxy must forward admin credentials accepted by the upstream Talos
+server. Batch verify (`POST /v2alpha1/admin/apiKeys:batchVerify`) is proxied transparently without caching.
```mermaid
sequenceDiagram
@@ -49,11 +49,11 @@ sequenceDiagram
participant Proxy as Edge Proxy
participant Talos as Upstream Talos
- App->>Proxy: POST /v2alpha1/verify/apiKey
+ App->>Proxy: POST /v2alpha1/admin/apiKeys:verify
alt Cache HIT
Proxy-->>App: 200 OK (cached, sub-ms)
else Cache MISS
- Proxy->>Talos: POST /v2alpha1/verify/apiKey
+ Proxy->>Talos: POST /v2alpha1/admin/apiKeys:verify
Talos-->>Proxy: 200 OK (active=true)
Note over Proxy: Cache response
Proxy-->>App: 200 OK
@@ -64,13 +64,12 @@ sequenceDiagram
Proxy-->>App: 200 OK
```
-Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the
-proxy transparently.
+Non-verify requests (admin operations, key issuance, health checks to upstream) pass through the proxy transparently.
## Sidecar deployment
-Run the proxy as a sidecar container alongside your application. Your application sends verify
-requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
+Run the proxy as a sidecar container alongside your application. Your application sends verify requests to `localhost` (sub-ms
+cache hits) instead of the central Talos server.
```
┌─────────────────────────────────┐
@@ -83,9 +82,8 @@ requests to `localhost` (sub-ms cache hits) instead of the central Talos server.
└─────────────────────────────────┘
```
-Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy
-listens on). All other Talos API calls (admin, key management) should go directly to the central
-server.
+Point your application's Talos verify URL at `http://localhost:8080` (or whichever port the proxy listens on). All other Talos API
+calls (admin, key management) should go directly to the central server.
## Configuration
@@ -113,16 +111,15 @@ talos-commercial proxy \
### Cache key generation
-Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent
-collision attacks. The host component ensures tenant isolation in multi-tenant deployments: the same
-credential cached under `tenant-a.example.com` will not be served for requests from
-`tenant-b.example.com`.
+Cache keys are derived from `SHA256(host + credential)` using length-prefixed encoding to prevent collision attacks. The host
+component ensures tenant isolation in multi-tenant deployments: the same credential cached under `tenant-a.example.com` will not
+be served for requests from `tenant-b.example.com`.
### What gets cached
Only responses that meet **all** of the following criteria are cached:
-- The request is a `POST` to `/v2alpha1/verify/*`
+- The request is a `POST` to `/v2alpha1/admin/apiKeys:verify` (exact match — batch verify is not cached)
- The upstream returned HTTP `200 OK`
- The response body contains `"is_active": true`
@@ -130,10 +127,9 @@ Inactive credentials, error responses, and non-verify endpoints are never cached
### TTL calculation
-The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the
-verification response includes an `expires_at` timestamp, the proxy ensures the cached entry expires
-no later than the credential itself. If `expires_at` is absent, the configured `--cache-ttl` is
-used.
+The effective TTL for each entry is `min(configured_ttl, time_until_expires_at)`. If the verification response includes an
+`expires_at` timestamp, the proxy ensures the cached entry expires no later than the credential itself. If `expires_at` is absent,
+the configured `--cache-ttl` is used.
### Cache headers
@@ -149,14 +145,14 @@ Every response from the proxy includes an `Ory-Talos-Cache` header:
Clients can bypass the cache by including a `Cache-Control` header:
```bash
-curl -X POST http://localhost:8080/v2alpha1/verify/apiKey \
+curl -X POST http://localhost:8080/v2alpha1/admin/apiKeys:verify \
-H "Content-Type: application/json" \
+ -H "Authorization: Bearer $TALOS_ADMIN_TOKEN" \
-H "Cache-Control: no-cache" \
-d '{"credential": "phx_..."}'
```
-Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for
-caching.
+Both `no-cache` and `no-store` directives trigger a cache bypass. The response is still eligible for caching.
## Health checks
@@ -271,10 +267,8 @@ spec:
## Eventual consistency
-Revocation takes effect in the database immediately but cached verification results persist until
-the cache TTL expires. To force an immediate re-check against upstream, send
-`Cache-Control: no-cache` on the verification request.
+Revocation takes effect in the database immediately but cached verification results persist until the cache TTL expires. To force
+an immediate re-check against upstream, send `Cache-Control: no-cache` on the verification request.
-Choose a `--cache-ttl` that balances latency savings against your revocation propagation
-requirements. Shorter TTLs provide faster revocation propagation at the cost of more upstream
-requests.
+Choose a `--cache-ttl` that balances latency savings against your revocation propagation requirements. Shorter TTLs provide faster
+revocation propagation at the cost of more upstream requests.
diff --git a/docs/talos/operate/deploy/kubernetes.md b/docs/talos/operate/deploy/kubernetes.md
index 77ff3948b3..62f75f5ba7 100644
--- a/docs/talos/operate/deploy/kubernetes.md
+++ b/docs/talos/operate/deploy/kubernetes.md
@@ -4,20 +4,19 @@ title: Kubernetes
# Kubernetes
-The OSS edition uses an embedded SQLite database, so it cannot scale horizontally — a multi-replica
-Deployment backed by a shared volume will corrupt under concurrent writes. Run the OSS image as a
-single replica or move to the [Commercial edition](../../index.md#editions) for Postgres, MySQL, or
-CockroachDB.
+The OSS edition uses an embedded SQLite database, so it cannot scale horizontally — a multi-replica Deployment backed by a shared
+volume will corrupt under concurrent writes. Run the OSS image as a single replica or move to the
+[Commercial edition](../../index.md#editions) for Postgres, MySQL, or CockroachDB.
-| Edition | Image | Backends | Replicas |
-| ---------- | ------------------------------ | ------------------------------------------- | ----------------------- |
-| OSS | `oryd/talos:latest` | SQLite (embedded) | 1 (single-node only) |
-| Commercial | `oryd/talos-commercial:latest` | PostgreSQL, MySQL, CockroachDB | Horizontally scalable |
+| Edition | Image | Backends | Replicas |
+| ---------- | ------------------------------ | ------------------------------ | --------------------- |
+| OSS | `oryd/talos:latest` | SQLite (embedded) | 1 (single-node only) |
+| Commercial | `oryd/talos-commercial:latest` | PostgreSQL, MySQL, CockroachDB | Horizontally scalable |
## Deployment (Commercial, scalable)
-The manifest below uses the commercial image and a SQL backend stored as `dsn` in a Kubernetes
-`Secret`. Adjust `replicas` to your traffic profile.
+The manifest below uses the commercial image and a SQL backend stored as `dsn` in a Kubernetes `Secret`. Adjust `replicas` to your
+traffic profile.
```yaml
apiVersion: apps/v1
diff --git a/docs/talos/operate/deploy/separate-planes.md b/docs/talos/operate/deploy/separate-planes.md
index 73ccdbef68..b3597ee446 100644
--- a/docs/talos/operate/deploy/separate-planes.md
+++ b/docs/talos/operate/deploy/separate-planes.md
@@ -4,22 +4,18 @@ title: Separate admin and data planes
# Separate admin and data planes
-In production, you can deploy the admin plane and data plane as separate processes for independent
-scaling and security isolation.
+In production, you can deploy the admin plane and data plane as separate processes for independent scaling and security isolation.
## Why run them separately
-- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be
- exposed at the edge
-- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane
- handles lower-volume management
-- **Network isolation**: Admin plane behind internal firewall; data plane behind public load
- balancer
+- **Security**: Admin plane (write operations) stays internal; data plane (verification) can be exposed at the edge
+- **Scaling**: Data plane handles high-throughput verification and scales horizontally; admin plane handles lower-volume
+ management
+- **Network isolation**: Admin plane behind internal firewall; data plane behind public load balancer
## Architecture
-Both planes share the same database. The admin plane writes keys; the data plane reads and verifies
-them.
+Both planes share the same database. The admin plane writes keys; the data plane reads and verifies them.
```mermaid
graph TB
@@ -53,12 +49,10 @@ talos serve check --config config.yaml
## Configuration
-Both deployments use the same config file or environment variables. The key difference is network
-exposure:
+Both deployments use the same config file or environment variables. The key difference is network exposure:
-Both processes need the full configuration block (`secrets`, `credentials`,
-`db`). The split is driven by the `serve` subcommand and the bind address, not
-by stripping config keys.
+Both processes need the full configuration block (`secrets`, `credentials`, `db`). The split is driven by the `serve` subcommand
+and the bind address, not by stripping config keys.
**Admin plane** — bind to an internal address:
@@ -76,10 +70,9 @@ secrets:
current: "use-the-same-hmac-secret-on-both-planes-or-verify-fails-64chars"
```
-**Data plane** — bind to all interfaces with caching. Use the same secrets and
-issuer as the admin plane so the two processes derive identical key checksums.
-If you co-locate both planes on the same host, change one port (for example, the
-admin plane on `4421`):
+**Data plane** — bind to all interfaces with caching. Use the same secrets and issuer as the admin plane so the two processes
+derive identical key checksums. If you co-locate both planes on the same host, change one port (for example, the admin plane on
+`4421`):
```yaml
serve:
@@ -100,5 +93,4 @@ cache:
## Network policies
-Restrict admin plane access to internal services only. Data plane can accept traffic from any
-source.
+Restrict admin plane access to internal services only. Data plane can accept traffic from any source.
diff --git a/docs/talos/operate/index.md b/docs/talos/operate/index.md
index f4a61e2667..3abd179410 100644
--- a/docs/talos/operate/index.md
+++ b/docs/talos/operate/index.md
@@ -5,9 +5,9 @@ description: Install, configure, and deploy Ory Talos
# Operate Ory Talos
-How to install, configure, deploy, and operate Talos. Pages tagged `[commercial]` apply to the
-Commercial edition only — the OSS edition runs as a single-node binary with embedded SQLite and
-covers the install, configure, secrets, TLS, monitoring, and security-hardening guides below.
+How to install, configure, deploy, and operate Talos. Pages tagged `[commercial]` apply to the Commercial edition only — the OSS
+edition runs as a single-node binary with embedded SQLite and covers the install, configure, secrets, TLS, monitoring, and
+security-hardening guides below.
## Getting started
@@ -22,19 +22,17 @@ Before going to production, review these guides (apply to OSS and Commercial):
- **[Secrets management](secrets.md)** — configure HMAC secrets and JWKS signing keys
- **[TLS](tls.md)** — enable TLS termination or configure a reverse proxy
-- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and
- health checks
-- **[Security hardening](security-hardening.md)** — production security checklist, including admin
- plane authentication
+- **[Monitoring](monitoring/index.md)** — set up Prometheus metrics, OpenTelemetry tracing, and health checks
+- **[Security hardening](security-hardening.md)** — production security checklist, including admin plane authentication
- **[Benchmarks](benchmarks.md)** — performance baselines and load testing
## Commercial-only features
-The OSS edition is single-node SQLite. Horizontal scale, SQL backends, distributed caching, edge
-deployment, and multi-tenancy require the [Commercial edition](../index.md#editions):
+The OSS edition is single-node SQLite. Horizontal scale, SQL backends, distributed caching, edge deployment, and multi-tenancy
+require the [Commercial edition](../index.md#editions):
-- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**,
- **[CockroachDB](database/cockroachdb.md)** — production-grade SQL backends
+- **[PostgreSQL](database/postgresql.md)**, **[MySQL](database/mysql.md)**, **[CockroachDB](database/cockroachdb.md)** —
+ production-grade SQL backends
- **[Caching](cache/index.md)** — in-memory and Redis caching for sub-millisecond verification
- **[Edge proxy](deploy/edge-proxy.md)** — deploy data plane at the edge
- **[Multi-tenancy](multi-tenancy.md)** — serve multiple tenants from a single cluster
@@ -46,6 +44,5 @@ Talos separates administrative operations (issuing, revoking) from verification:
- **Admin plane** — manages key lifecycle. Runs behind your internal network.
- **Data plane** — verifies credentials at the edge. Horizontally scalable with caching.
-You can run both planes in a single process (`talos serve`) or split them for production
-(`talos serve admin`, `talos serve check`). See [Separate planes](deploy/separate-planes.md) for
-details.
+You can run both planes in a single process (`talos serve`) or split them for production (`talos serve admin`,
+`talos serve check`). See [Separate planes](deploy/separate-planes.md) for details.
diff --git a/docs/talos/operate/install.md b/docs/talos/operate/install.md
index 36283132ad..e893fec2df 100644
--- a/docs/talos/operate/install.md
+++ b/docs/talos/operate/install.md
@@ -23,8 +23,7 @@ The binary is at `.bin/talos`. SQLite is the only supported database backend in
### Commercial edition
-The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin
-UI:
+The Commercial edition adds PostgreSQL, MySQL, CockroachDB, caching, multi-tenancy, and the admin UI:
```bash
go build -tags commercial -o .bin/talos-commercial .
diff --git a/docs/talos/operate/monitoring/health-checks.md b/docs/talos/operate/monitoring/health-checks.md
index eec21edfee..b3fce3f677 100644
--- a/docs/talos/operate/monitoring/health-checks.md
+++ b/docs/talos/operate/monitoring/health-checks.md
@@ -34,8 +34,8 @@ readinessProbe:
## Load balancer
-Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server
-is ready to accept traffic and 503 when it is not (e.g., during startup or shutdown).
+Point your load balancer health check at `/health/ready`. This endpoint returns 200 when the server is ready to accept traffic and
+503 when it is not (e.g., during startup or shutdown).
## Suppressing health logs
diff --git a/docs/talos/operate/monitoring/index.md b/docs/talos/operate/monitoring/index.md
index 003e735225..f0a92dbdad 100644
--- a/docs/talos/operate/monitoring/index.md
+++ b/docs/talos/operate/monitoring/index.md
@@ -4,8 +4,7 @@ title: Monitoring
# Monitoring
-Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health
-endpoints.
+Talos provides built-in observability through Prometheus metrics, OpenTelemetry tracing, and health endpoints.
- [Prometheus metrics](metrics.md) — request counts, latencies, and pool sizes
- [OpenTelemetry tracing](tracing.md) — distributed request traces
diff --git a/docs/talos/operate/monitoring/metrics.md b/docs/talos/operate/monitoring/metrics.md
index 88371cd9a1..09116feed2 100644
--- a/docs/talos/operate/monitoring/metrics.md
+++ b/docs/talos/operate/monitoring/metrics.md
@@ -24,10 +24,10 @@ GET http://localhost:4422/metrics
### Labels
-| Label | Description | Used by |
-| ---------- | --------------------------------------------------------- | ------------------------------------------------------ |
-| `method` | HTTP method (lowercase) | All except `http_requests_in_flight` |
-| `code` | HTTP status code | All except `http_requests_in_flight` |
+| Label | Description | Used by |
+| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ |
+| `method` | HTTP method (lowercase) | All except `http_requests_in_flight` |
+| `code` | HTTP status code | All except `http_requests_in_flight` |
| `endpoint` | Route template (e.g., `/v2alpha1/admin/issuedApiKeys/{key_id}`) | `http_requests_total`, `http_request_duration_seconds` |
## Configuration
diff --git a/docs/talos/operate/monitoring/tracing.md b/docs/talos/operate/monitoring/tracing.md
index 9bb00521b5..43baf48812 100644
--- a/docs/talos/operate/monitoring/tracing.md
+++ b/docs/talos/operate/monitoring/tracing.md
@@ -36,6 +36,5 @@ export TALOS_TRACING_SAMPLE_RATE=0.01
## Traced operations
-Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP
-request handling. Each trace includes the Network ID (for multi-tenant deployments) and relevant key
-identifiers.
+Talos traces database queries, HMAC operations, cache lookups, key verification paths, and HTTP request handling. Each trace
+includes the Network ID (for multi-tenant deployments) and relevant key identifiers.
diff --git a/docs/talos/operate/multi-tenancy.md b/docs/talos/operate/multi-tenancy.md
index 3140c7ea1e..8f2634581e 100644
--- a/docs/talos/operate/multi-tenancy.md
+++ b/docs/talos/operate/multi-tenancy.md
@@ -7,18 +7,16 @@ sidebar_custom_props:
# Multi-tenancy
-Talos supports multi-tenancy through Network IDs (NID) derived from the request hostname. Each
-tenant runs on its own hostname and has its own NID, configuration overlay, and isolated data.
+Talos supports multi-tenancy through Network IDs (NID) derived from the request hostname. Each tenant runs on its own hostname and
+has its own NID, configuration overlay, and isolated data.
## How it works
1. Each tenant is assigned a unique Network ID (UUID).
-2. The hostname middleware extracts the hostname from the incoming request, normalizes it, and
- resolves it to a configured tenant.
-3. The contextualizer attaches the NID and any per-tenant configuration overlay to the request
- context.
-4. All database operations are scoped to the NID via composite primary keys `(nid, key_id)`. Keys
- created in one tenant cannot be accessed or verified in another.
+2. The hostname middleware extracts the hostname from the incoming request, normalizes it, and resolves it to a configured tenant.
+3. The contextualizer attaches the NID and any per-tenant configuration overlay to the request context.
+4. All database operations are scoped to the NID via composite primary keys `(nid, key_id)`. Keys created in one tenant cannot be
+ accessed or verified in another.
## Configuration
@@ -34,19 +32,17 @@ multitenancy:
config_path: "/etc/talos/tenant2.yaml"
```
-| Field | Required | Description |
-| ------------- | -------- | ------------------------------------------------------------------------------------ |
-| `hostname` | Yes | Tenant hostname matched against the normalized request hostname (see below) |
-| `id` | Yes | Tenant UUID written to the `nid` column of every row created on this tenant |
-| `config_path` | No | Path to a YAML file containing per-tenant business-logic overrides (see below) |
+| Field | Required | Description |
+| ------------- | -------- | ------------------------------------------------------------------------------ |
+| `hostname` | Yes | Tenant hostname matched against the normalized request hostname (see below) |
+| `id` | Yes | Tenant UUID written to the `nid` column of every row created on this tenant |
+| `config_path` | No | Path to a YAML file containing per-tenant business-logic overrides (see below) |
-Hostnames must be unique after normalization. Talos refuses to start if two entries normalize to
-the same value.
+Hostnames must be unique after normalization. Talos refuses to start if two entries normalize to the same value.
## Hostname source and normalization
-By default Talos uses `r.Host` (the HTTP `Host` header) for tenant routing. To prefer
-`X-Forwarded-Host`, set:
+By default Talos uses `r.Host` (the HTTP `Host` header) for tenant routing. To prefer `X-Forwarded-Host`, set:
```yaml
serve:
@@ -54,61 +50,56 @@ serve:
trust_forwarded_host: true
```
-Set this **only** when Talos runs behind a reverse proxy that strips the client-supplied
-`X-Forwarded-Host` and rewrites it to the canonical edge hostname. Trusting the header in front of
-an unfiltered ingress lets external callers spoof tenant identity by sending a forged
-`X-Forwarded-Host`.
+Set this **only** when Talos runs behind a reverse proxy that strips the client-supplied `X-Forwarded-Host` and rewrites it to the
+canonical edge hostname. Trusting the header in front of an unfiltered ingress lets external callers spoof tenant identity by
+sending a forged `X-Forwarded-Host`.
Hostnames are normalized before lookup:
- Lowercased (`Tenant1.Example.com` → `tenant1.example.com`)
- Port stripped (`tenant1.example.com:8443` → `tenant1.example.com`)
- IPv6 brackets stripped (`[2001:db8::1]:443` → `2001:db8::1`)
-- Rejected if the bare hostname exceeds 253 characters (DNS maximum), contains null bytes, or
- contains non-printable runes — these requests are treated as if the hostname is unknown.
+- Rejected if the bare hostname exceeds 253 characters (DNS maximum), contains null bytes, or contains non-printable runes — these
+ requests are treated as if the hostname is unknown.
## Unknown hostname behavior
-Requests whose normalized hostname does not match any configured network return HTTP `404` with
-`code: NOT_FOUND` and reason `network not found`. The middleware does not fall back to a default
-tenant. Configure a wildcard or catch-all hostname explicitly if you need one.
+Requests whose normalized hostname does not match any configured network return HTTP `404` with `code: NOT_FOUND` and reason
+`network not found`. The middleware does not fall back to a default tenant. Configure a wildcard or catch-all hostname explicitly
+if you need one.
## Per-tenant configuration overlays
-`config_path` points to a YAML file merged on top of the base server configuration at request
-time. Per-tenant overlays are **business-logic only**:
+`config_path` points to a YAML file merged on top of the base server configuration at request time. Per-tenant overlays are
+**business-logic only**:
-| Allowed override prefixes | Purpose |
-| --------------------------------------- | ------------------------------------------------ |
-| `talos.*` | Tenant-specific business logic |
-| `secrets.*` | Per-tenant HMAC and pagination secrets |
-| `credentials.*` | Per-tenant key prefixes, issuer, JWKS URLs |
-| `cache.*` | Per-tenant cache backend selection |
+| Allowed override prefixes | Purpose |
+| ------------------------- | ------------------------------------------ |
+| `talos.*` | Tenant-specific business logic |
+| `secrets.*` | Per-tenant HMAC and pagination secrets |
+| `credentials.*` | Per-tenant key prefixes, issuer, JWKS URLs |
+| `cache.*` | Per-tenant cache backend selection |
-Server-wide settings — `db.*`, `serve.*` (`http`, `grpc`, `tls`), `multitenancy.*`,
-`tracing.*` — are **always global** and cannot be overridden per tenant. Setting them in a tenant
-overlay has no effect.
+Server-wide settings — `db.*`, `serve.*` (`http`, `grpc`, `tls`), `multitenancy.*`, `tracing.*` — are **always global** and cannot
+be overridden per tenant. Setting them in a tenant overlay has no effect.
## Database isolation
-Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every
-query includes the NID, ensuring complete data isolation at the SQL level. Cross-tenant queries
-are impossible from application code because the NID is read from the request context, never from
-request parameters or response bodies.
+Both `api_keys` and `imported_api_keys` tables use composite primary keys `(nid, key_id)`. Every query includes the NID, ensuring
+complete data isolation at the SQL level. Cross-tenant queries are impossible from application code because the NID is read from
+the request context, never from request parameters or response bodies.
## Defense-in-depth
-Token claims embed the NID at derivation time. During verification, the claim NID is validated
-against the context NID (from hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`,
-preventing cross-tenant token replay.
+Token claims embed the NID at derivation time. During verification, the claim NID is validated against the context NID (from
+hostname). A mismatch returns `VERIFICATION_ERROR_NOT_FOUND`, preventing cross-tenant token replay.
## Provisioning a new tenant
1. **Generate a tenant UUID:** `uuidgen` (or `python -c 'import uuid; print(uuid.uuid4())'`).
-2. **Pick a hostname** that resolves to your Talos data plane (e.g., `tenant3.talos.example.com`)
- and add a DNS record or load-balancer rule for it.
-3. **Create the tenant overlay** at `/etc/talos/tenant3.yaml` with any per-tenant business
- settings:
+2. **Pick a hostname** that resolves to your Talos data plane (e.g., `tenant3.talos.example.com`) and add a DNS record or
+ load-balancer rule for it.
+3. **Create the tenant overlay** at `/etc/talos/tenant3.yaml` with any per-tenant business settings:
```yaml
credentials:
@@ -139,7 +130,6 @@ preventing cross-tenant token replay.
The response should include the new tenant's prefix (`t3_v1_…`).
-To deprovision a tenant, remove the entry from `multitenancy.networks` and reload. Existing keys
-remain in the database under that NID; delete them with a tenant-scoped admin call before
-removing the entry, or run a SQL `DELETE FROM api_keys WHERE nid = ''` after the entry is
-gone.
+To deprovision a tenant, remove the entry from `multitenancy.networks` and reload. Existing keys remain in the database under that
+NID; delete them with a tenant-scoped admin call before removing the entry, or run a SQL
+`DELETE FROM api_keys WHERE nid = ''` after the entry is gone.
diff --git a/docs/talos/operate/secrets.md b/docs/talos/operate/secrets.md
index 57d70f7552..2f1b9264d4 100644
--- a/docs/talos/operate/secrets.md
+++ b/docs/talos/operate/secrets.md
@@ -6,11 +6,10 @@ title: Secret management
Talos uses two independent secret families:
-- `secrets.hmac.*` — keys API key checksums and derives the macaroon root key. **Required at
- startup**; Talos exits with `project has no HMAC key configured` if `secrets.hmac.current` is
- unset.
-- `secrets.pagination.*` (preferred) or `secrets.default.*` (fallback) — encrypts opaque
- pagination tokens. Required to use list endpoints.
+- `secrets.hmac.*` — keys API key checksums and derives the macaroon root key. **Required at startup**; Talos exits with
+ `project has no HMAC key configured` if `secrets.hmac.current` is unset.
+- `secrets.pagination.*` (preferred) or `secrets.default.*` (fallback) — encrypts opaque pagination tokens. Required to use list
+ endpoints.
Each secret must be at least 32 characters. Use 64 random characters for new deployments.
@@ -28,54 +27,49 @@ secrets:
- "previous-pagination-token-secret-rotated-out-on-2026-03-01--64chars"
```
-If `secrets.pagination.current` is empty, Talos falls back to `secrets.default.current`. Use
-`secrets.pagination.*` for new deployments; `secrets.default.*` is retained for backwards
-compatibility with earlier configurations.
+If `secrets.pagination.current` is empty, Talos falls back to `secrets.default.current`. Use `secrets.pagination.*` for new
+deployments; `secrets.default.*` is retained for backwards compatibility with earlier configurations.
## Secret types
-| Secret | Purpose | Required |
-| ---------------------------- | ---------------------------------------------------------------- | ----------------------- |
-| `secrets.hmac.current` | API key checksum HMAC and macaroon root-key derivation | Yes (min 32 chars) |
-| `secrets.hmac.retired` | Older HMAC secrets accepted during verification only | No |
-| `secrets.pagination.current` | Pagination-token encryption (preferred over `secrets.default`) | One of pagination/default required for list endpoints |
-| `secrets.pagination.retired` | Older pagination secrets accepted during decryption only | No |
-| `secrets.default.current` | Pagination-token fallback when `secrets.pagination.current` unset | No (use `pagination.*`) |
-| `secrets.default.retired` | Older fallback secrets accepted during decryption only | No |
+| Secret | Purpose | Required |
+| ---------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
+| `secrets.hmac.current` | API key checksum HMAC and macaroon root-key derivation | Yes (min 32 chars) |
+| `secrets.hmac.retired` | Older HMAC secrets accepted during verification only | No |
+| `secrets.pagination.current` | Pagination-token encryption (preferred over `secrets.default`) | One of pagination/default required for list endpoints |
+| `secrets.pagination.retired` | Older pagination secrets accepted during decryption only | No |
+| `secrets.default.current` | Pagination-token fallback when `secrets.pagination.current` unset | No (use `pagination.*`) |
+| `secrets.default.retired` | Older fallback secrets accepted during decryption only | No |
-The HMAC and pagination secret families are independent. Rotate them on independent schedules and
-never reuse the same value across families.
+The HMAC and pagination secret families are independent. Rotate them on independent schedules and never reuse the same value
+across families.
## Macaroon root-key derivation
-Talos does not store a separate macaroon signing secret. The macaroon root key is derived
-deterministically from `secrets.hmac.current` using a domain-separated HMAC-SHA256:
+Talos does not store a separate macaroon signing secret. The macaroon root key is derived deterministically from
+`secrets.hmac.current` using a domain-separated HMAC-SHA256:
```
macaroon_root_key = HMAC-SHA256(secrets.hmac.current, "talos/macaroon/v1/root-key")
```
-The fixed domain string `talos/macaroon/v1/root-key` prevents the derived key from colliding with
-other uses of the HMAC secret (such as API key checksums). All admin and data plane processes
-configured with the same `secrets.hmac.current` derive the same macaroon root key, so any node can
-verify macaroons issued by any other node without out-of-band key distribution.
+The fixed domain string `talos/macaroon/v1/root-key` prevents the derived key from colliding with other uses of the HMAC secret
+(such as API key checksums). All admin and data plane processes configured with the same `secrets.hmac.current` derive the same
+macaroon root key, so any node can verify macaroons issued by any other node without out-of-band key distribution.
-Rotating `secrets.hmac.current` rotates both the API key checksum key and the macaroon root key
-at once. Verification falls back through `secrets.hmac.retired` for both purposes.
+Rotating `secrets.hmac.current` rotates both the API key checksum key and the macaroon root key at once. Verification falls back
+through `secrets.hmac.retired` for both purposes.
## Pagination-token secret
-List endpoints (`ListIssuedAPIKeys`, `ListImportedAPIKeys`, `ListBatchVerifications`, …) return an
-opaque `next_page_token` that encrypts the cursor (key ID and tenant ID) with NaCl secretbox. The
-encryption key is derived from `secrets.pagination.current` (or `secrets.default.current` as a
-fallback).
+List endpoints (`ListIssuedAPIKeys`, `ListImportedAPIKeys`, `ListBatchVerifications`, …) return an opaque `next_page_token` that
+encrypts the cursor (key ID and tenant ID) with NaCl secretbox. The encryption key is derived from `secrets.pagination.current`
+(or `secrets.default.current` as a fallback).
-Page tokens are tenant-scoped: a token issued under tenant A returns
-`page token network mismatch` if replayed against tenant B.
+Page tokens are tenant-scoped: a token issued under tenant A returns `page token network mismatch` if replayed against tenant B.
-Rotating the pagination secret invalidates outstanding tokens unless the previous secret remains
-in the `retired` list. Keep the previous secret in `retired` for at least the longest paging
-session you expect (typically a few minutes).
+Rotating the pagination secret invalidates outstanding tokens unless the previous secret remains in the `retired` list. Keep the
+previous secret in `retired` for at least the longest paging session you expect (typically a few minutes).
## Secret rotation
@@ -91,9 +85,8 @@ secrets:
- "previous-hmac-secret-still-trusted-during-verification-padded--"
```
-During verification, Talos tries `current` first, then each entry in `retired` in order. New keys
-are always issued with `current`. Remove a value from `retired` only after every key issued with it
-has expired or been rotated.
+During verification, Talos tries `current` first, then each entry in `retired` in order. New keys are always issued with
+`current`. Remove a value from `retired` only after every key issued with it has expired or been rotated.
## Generating secrets
@@ -114,5 +107,5 @@ export TALOS_SECRETS_PAGINATION_RETIRED="previous-pagination-secret-1"
export TALOS_SECRETS_DEFAULT_CURRENT="64-char-fallback-pagination-secret"
```
-Inject these from a secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, or
-Kubernetes `Secret`); never check secrets into version control.
+Inject these from a secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, or Kubernetes `Secret`); never
+check secrets into version control.
diff --git a/docs/talos/operate/security-hardening.md b/docs/talos/operate/security-hardening.md
index 8b0865cec3..0f08c2686b 100644
--- a/docs/talos/operate/security-hardening.md
+++ b/docs/talos/operate/security-hardening.md
@@ -6,35 +6,32 @@ title: Security hardening
## Network
-- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance
- and revocation and should never be exposed to the public internet.
-- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or
- terminate TLS at the load balancer).
+- **Restrict admin plane access** to internal networks only. The admin plane handles key issuance and revocation and should never
+ be exposed to the public internet.
+- **Use TLS** for all connections. Configure database `sslmode=verify-full` and serve HTTPS (or terminate TLS at the load
+ balancer).
- **Separate admin and data planes** in production for independent security boundaries.
## Secrets
-- **Configure both required secrets** before starting Talos: `secrets.default.current` (pagination
- tokens) and `secrets.hmac.current` (API key checksums and macaroon root keys). Both must be at
- least 32 characters; aim for 64 random characters.
+- **Configure both required secrets** before starting Talos: `secrets.default.current` (pagination tokens) and
+ `secrets.hmac.current` (API key checksums and macaroon root keys). Both must be at least 32 characters; aim for 64 random
+ characters.
- **Generate secrets cryptographically**: `openssl rand -base64 48 | tr -d '\n+/=' | cut -c1-64`.
-- **Rotate secrets regularly** by promoting `current` to `retired` and setting a new `current`.
- Verification tries `current` first, then every value in `retired`, so existing keys keep
- working through the rotation window.
-- **Never commit secrets** to version control. Inject them via environment variables
- (`TALOS_SECRETS_DEFAULT_CURRENT`, `TALOS_SECRETS_HMAC_CURRENT`) or a secrets manager.
+- **Rotate secrets regularly** by promoting `current` to `retired` and setting a new `current`. Verification tries `current`
+ first, then every value in `retired`, so existing keys keep working through the rotation window.
+- **Never commit secrets** to version control. Inject them via environment variables (`TALOS_SECRETS_DEFAULT_CURRENT`,
+ `TALOS_SECRETS_HMAC_CURRENT`) or a secrets manager.
## API keys
- **Set TTL on all keys** to limit exposure from leaked credentials.
-- **Revoke compromised keys immediately** using
- `POST /v2alpha1/admin/issuedApiKeys/{key_id}:revoke` or
- `POST /v2alpha1/admin/importedApiKeys/{key_id}:revoke`.
-- **Limit scopes** on issued and imported keys to the minimum required. Talos stores scopes as
- metadata on the key and returns them on verification; your application is responsible for
- enforcing them during request handling.
-- **Bind keys to caller IPs** with `ip_restriction.allowed_cidrs` to reduce blast radius if a key
- leaks. See [IP restrictions](../integrate/ip-restrictions.md).
+- **Revoke compromised keys immediately** using `POST /v2alpha1/admin/apiKeys/{key_id}:revoke`. The same endpoint handles both
+ issued and imported keys.
+- **Limit scopes** on issued and imported keys to the minimum required. Talos stores scopes as metadata on the key and returns
+ them on verification; your application is responsible for enforcing them during request handling.
+- **Bind keys to caller IPs** with `ip_restriction.allowed_cidrs` to reduce blast radius if a key leaks. See
+ [IP restrictions](../integrate/ip-restrictions.mdx).
## Caching
@@ -49,25 +46,23 @@ title: Security hardening
## Admin plane authentication
-**Talos ships no built-in authentication for the admin plane.** Any caller that can reach the admin
-HTTP listener can issue, update, and revoke keys for any tenant. Treat the admin plane as a trusted
-internal service and put authentication in front of it.
+**Talos ships no built-in authentication for the admin plane.** Any caller that can reach the admin HTTP listener can issue,
+update, and revoke keys for any tenant. Treat the admin plane as a trusted internal service and put authentication in front of it.
Recommended patterns:
-- **Identity-aware proxy (IAP)**: terminate authentication at a gateway (Google Cloud IAP, AWS ALB
- with Cognito, Cloudflare Access, oauth2-proxy) and forward only authenticated requests to the
- admin plane. Pin the admin listener to a private network so requests cannot bypass the gateway.
-- **mTLS at the load balancer**: require client certificates issued by an internal CA. Reject
- unauthenticated TLS handshakes at the LB, then forward plain HTTP to the admin plane on a
- private network.
-- **Service mesh policy**: in Kubernetes, use Istio `AuthorizationPolicy` or Linkerd authorization
- policies to allow only specific service accounts to call the admin plane.
+- **Identity-aware proxy (IAP)**: terminate authentication at a gateway (Google Cloud IAP, AWS ALB with Cognito, Cloudflare
+ Access, oauth2-proxy) and forward only authenticated requests to the admin plane. Pin the admin listener to a private network so
+ requests cannot bypass the gateway.
+- **mTLS at the load balancer**: require client certificates issued by an internal CA. Reject unauthenticated TLS handshakes at
+ the LB, then forward plain HTTP to the admin plane on a private network.
+- **Service mesh policy**: in Kubernetes, use Istio `AuthorizationPolicy` or Linkerd authorization policies to allow only specific
+ service accounts to call the admin plane.
Whichever pattern you choose:
-- Bind the admin listener to a non-routable address (`127.0.0.1`, `10.x`, or a Kubernetes
- `ClusterIP`); never expose it to the public internet.
-- Run the data plane on a separate listener so verification traffic does not need to traverse the
- admin auth path. See [Separate admin and data planes](deploy/separate-planes.md).
+- Bind the admin listener to a non-routable address (`127.0.0.1`, `10.x`, or a Kubernetes `ClusterIP`); never expose it to the
+ public internet.
+- Run the data plane on a separate listener so verification traffic does not need to traverse the admin auth path. See
+ [Separate admin and data planes](deploy/separate-planes.md).
- Audit-log every admin call at the gateway. Talos itself does not record caller identity.
diff --git a/docs/talos/operate/tls.md b/docs/talos/operate/tls.md
index 6e630b71ba..5e108ed273 100644
--- a/docs/talos/operate/tls.md
+++ b/docs/talos/operate/tls.md
@@ -4,8 +4,7 @@ title: TLS configuration
# TLS configuration
-Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy,
-Caddy) for TLS termination:
+Talos does not have built-in TLS support for its HTTP server. Use a reverse proxy (nginx, Envoy, Caddy) for TLS termination:
```
Client --[HTTPS]--> Load Balancer --[HTTP]--> Talos
diff --git a/docs/talos/operate/troubleshooting.md b/docs/talos/operate/troubleshooting.md
index 0e4cca1bed..8fa97a2030 100644
--- a/docs/talos/operate/troubleshooting.md
+++ b/docs/talos/operate/troubleshooting.md
@@ -29,8 +29,7 @@ Verify `serve.http.host` and `serve.http.port` in your config.
talos migrate status --database "sqlite:///path/to/db"
```
-If a migration failed partway through, inspect the database schema and retry with
-`talos migrate up`.
+If a migration failed partway through, inspect the database schema and retry with `talos migrate up`.
### Secret too short
@@ -45,13 +44,12 @@ Set `secrets.default.current` to a string of at least 32 characters.
1. Verify the key was issued on the same Talos instance (or shared database)
2. Check if the key has been revoked: `GET /v2alpha1/admin/issuedApiKeys/{key_id}`
3. If using caching, try with `Cache-Control: no-cache` header
-4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was
- issued
+4. For multi-tenant deployments, verify the request hostname matches the tenant where the key was issued
### Invalid API key format
-The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret
-(not the key_id) is being sent.
+The credential does not match the `prefix_v1_identifier_checksum` format. Check that the full secret (not the key_id) is being
+sent.
## Debug logging
diff --git a/docs/talos/quickstart/docker-commercial.md b/docs/talos/quickstart/docker-commercial.mdx
similarity index 84%
rename from docs/talos/quickstart/docker-commercial.md
rename to docs/talos/quickstart/docker-commercial.mdx
index 561c3d6a25..d149f8f79b 100644
--- a/docs/talos/quickstart/docker-commercial.md
+++ b/docs/talos/quickstart/docker-commercial.mdx
@@ -5,7 +5,8 @@ sidebar_custom_props:
badge: Commercial
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Docker quickstart (Commercial)
@@ -40,8 +41,7 @@ RESPONSE=$(talos keys issue "commercial-test" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
```
@@ -63,8 +63,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
```
@@ -109,11 +108,10 @@ docker compose -f docker-compose.commercial.yaml down -v
## Prerequisites
-You need Docker and Docker Compose installed. See the [OSS quickstart](./index.md) to try the free
-edition first.
+You need Docker and Docker Compose installed. See the [OSS quickstart](./index.mdx) to try the free edition first.
## Next steps
-- [Quickstart (OSS)](./index.md) — simpler setup with SQLite
+- [Quickstart (OSS)](./index.mdx) — simpler setup with SQLite
- [Architecture](../concepts/architecture.md) — admin and data plane design
- [Caching](../concepts/caching.md) — cache behavior and consistency model
diff --git a/docs/talos/quickstart/index.md b/docs/talos/quickstart/index.mdx
similarity index 82%
rename from docs/talos/quickstart/index.md
rename to docs/talos/quickstart/index.mdx
index db504c9abf..e5816af1b3 100644
--- a/docs/talos/quickstart/index.md
+++ b/docs/talos/quickstart/index.mdx
@@ -3,12 +3,13 @@ title: Quickstart
description: Issue and verify your first API key in 5 minutes
---
-import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
# Quickstart
-This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker
-Compose. You need Docker. Examples use the Talos CLI (with curl as an alternative).
+This guide walks you through issuing, verifying, and revoking an API key with Ory Talos using Docker Compose. You need Docker.
+Examples use the Talos CLI (with curl as an alternative).
@@ -19,8 +20,8 @@ Compose. You need Docker. Examples use the Talos CLI (with curl as an alternativ
docker compose -f docker-compose.oss.yaml up --build -d
```
-This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at
-http://localhost:3001). Migrations run automatically.
+This starts Talos with SQLite, Jaeger for tracing, and the Admin UI (available at http://localhost:3001). Migrations run
+automatically.
Wait for the server to become healthy:
@@ -62,11 +63,8 @@ RESPONSE=$(talos keys issue "My first key" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -86,11 +84,8 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
# Save the secret and key ID for later steps
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -128,8 +123,7 @@ echo "$VERIFY_RESPONSE" | jq .
-The response confirms the key is active and returns the associated metadata (actor, scopes,
-expiration).
+The response confirms the key is active and returns the associated metadata (actor, scopes, expiration).
## Revoke the key
@@ -193,8 +187,8 @@ fi
-Revocation is immediate. Even though the key is cryptographically valid, the server checks the
-revocation list on every verification request.
+Revocation is immediate. Even though the key is cryptographically valid, the server checks the revocation list on every
+verification request.
## Stop the server
@@ -210,7 +204,6 @@ docker compose -f docker-compose.oss.yaml down -v
## Next steps
-- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential
- operations
+- **[Integration guide](../integrate/index.md)** — detailed API walkthrough for all credential operations
- **[Operations guide](../operate/index.md)** — install, configure, and deploy Talos in production
- **[Architecture](../concepts/architecture.md)** — how the admin and data planes work
diff --git a/docs/talos/quickstart/preview.mdx b/docs/talos/quickstart/preview.mdx
index 8e9a0a052c..2a863e3a2f 100644
--- a/docs/talos/quickstart/preview.mdx
+++ b/docs/talos/quickstart/preview.mdx
@@ -16,10 +16,10 @@ steps below; the `curl` examples are the preview baseline, and the Talos CLI is
1. Download `keyfile.json` from the email you received.
2. Authenticate with Google Cloud:
- ```bash
- gcloud auth activate-service-account --key-file=keyfile.json
- gcloud auth configure-docker europe-docker.pkg.dev
- ```
+ ```bash
+ gcloud auth activate-service-account --key-file=keyfile.json
+ gcloud auth configure-docker europe-docker.pkg.dev
+ ```
## Pull the image
@@ -148,11 +148,8 @@ RESPONSE=$(docker run --rm --network talos-preview \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -170,11 +167,8 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
echo "$RESPONSE" | jq .
-API_SECRET=$(echo "$RESPONSE" | jq -r '.secret')
-KEY_ID=$(echo "$RESPONSE" | jq -r '.issued_api_key.key_id')
-
-echo "export API_SECRET=$API_SECRET" >> "$DOCTEST_ENV_FILE"
-echo "export KEY_ID=$KEY_ID" >> "$DOCTEST_ENV_FILE"
+export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
+export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')
```
@@ -236,8 +230,7 @@ RESPONSE=$(docker run --rm --network talos-preview \
echo "$RESPONSE" | jq .
-JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+export JWT_TOKEN=$(echo "$RESPONSE" | jq -er '.token.token')
```
@@ -255,8 +248,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:derive" \
echo "$RESPONSE" | jq .
-JWT_TOKEN=$(echo "$RESPONSE" | jq -r '.token.token')
-echo "export JWT_TOKEN=$JWT_TOKEN" >> "$DOCTEST_ENV_FILE"
+export JWT_TOKEN=$(echo "$RESPONSE" | jq -er '.token.token')
```
@@ -275,7 +267,7 @@ Import a raw key string into Talos without rotating the credential. For the comp
```bash
-IMPORTED_RAW_KEY=sk_preview_demo_001
+export IMPORTED_RAW_KEY=sk_preview_demo_001
RESPONSE=$(docker run --rm --network talos-preview \
europe-docker.pkg.dev/ory-artifacts/ory-enterprise-talos/talos-oel:26.2.8 \
@@ -289,17 +281,14 @@ RESPONSE=$(docker run --rm --network talos-preview \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-
-echo "export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY" >> "$DOCTEST_ENV_FILE"
-echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.imported_api_key.key_id')
```
```bash
-IMPORTED_RAW_KEY=sk_preview_demo_001
+export IMPORTED_RAW_KEY=sk_preview_demo_001
RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
-H "Content-Type: application/json" \
@@ -313,10 +302,7 @@ RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
echo "$RESPONSE" | jq .
-IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -r '.imported_api_key.key_id')
-
-echo "export IMPORTED_RAW_KEY=$IMPORTED_RAW_KEY" >> "$DOCTEST_ENV_FILE"
-echo "export IMPORTED_KEY_ID=$IMPORTED_KEY_ID" >> "$DOCTEST_ENV_FILE"
+export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.imported_api_key.key_id')
```
@@ -362,10 +348,10 @@ docker network rm talos-preview
## Next steps
-- [Issue and verify API keys](../integrate/issue-and-verify.md) — issued-key lifecycle in depth
-- [Import existing keys](../integrate/import-keys.md) — batch import and hashing behavior
-- [Derive tokens](../integrate/derive-tokens.md) — JWT vs macaroon and JWKS usage
-- [Key lifecycle](../integrate/key-lifecycle.md) — rotate, update, and revoke credentials
+- [Issue and verify API keys](../integrate/issue-and-verify.mdx) — issued-key lifecycle in depth
+- [Import existing keys](../integrate/import-keys.mdx) — batch import and hashing behavior
+- [Derive tokens](../integrate/derive-tokens.mdx) — JWT vs macaroon and JWKS usage
+- [Key lifecycle](../integrate/key-lifecycle.mdx) — rotate, update, and revoke credentials
- [Architecture](../concepts/architecture.md) — admin and data plane separation
- [Cache configuration](../operate/cache/index.md) — switch from memory cache to Redis
-- [Docker quickstart (Commercial)](./docker-commercial.md) — full repo-based compose stack
+- [Docker quickstart (Commercial)](./docker-commercial.mdx) — full repo-based compose stack
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
index efd9ab9d68..cd642dad2b 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.RequestSchema.json
@@ -1 +1,102 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","properties":{"requests":{"items":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"actor_id":{"description":"actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"},"title":"Keys to import","type":"array"}},"type":"object","title":"v2alpha1BatchImportAPIKeysRequest"}}},"description":"BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "properties": {
+ "requests": {
+ "items": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "actor_id": {
+ "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ },
+ "title": "Keys to import",
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1BatchImportAPIKeysRequest"
+ }
+ }
+ },
+ "description": "BatchImportAPIKeysRequest imports multiple external API keys in one request.\nThe maximum batch size is 1000 keys.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
index cd904284dd..7239244613 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.StatusCodes.json
@@ -1 +1,185 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"BatchImportAPIKeysResponse returns per-item results and summary counters.","properties":{"failure_count":{"format":"int32","type":"integer"},"results":{"items":{"description":"BatchImportResult contains the result for one key in a batch import request.","properties":{"error_code":{"default":"BATCH_IMPORT_ERROR_UNSPECIFIED","description":"BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import","enum":["BATCH_IMPORT_ERROR_UNSPECIFIED","BATCH_IMPORT_ERROR_INVALID_ARGUMENT","BATCH_IMPORT_ERROR_ALREADY_EXISTS","BATCH_IMPORT_ERROR_FAILED_PRECONDITION","BATCH_IMPORT_ERROR_INTERNAL"],"type":"string","title":"v2alpha1BatchImportErrorCode"},"error_message":{"title":"Human-readable failure reason","type":"string"},"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"},"index":{"format":"int32","title":"Zero-based index in request.requests","type":"integer"}},"type":"object","title":"v2alpha1BatchImportResult"},"type":"array"},"success_count":{"format":"int32","type":"integer"}},"type":"object","title":"v2alpha1BatchImportAPIKeysResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"Batch import completed. Check per-item results for individual status."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "BatchImportAPIKeysResponse returns per-item results and summary counters.",
+ "properties": {
+ "failure_count": { "format": "int32", "type": "integer" },
+ "results": {
+ "items": {
+ "description": "BatchImportResult contains the result for one key in a batch import request.",
+ "properties": {
+ "error_code": {
+ "default": "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "description": "BatchImportErrorCode classifies per-item batch import failures.\n\n - BATCH_IMPORT_ERROR_UNSPECIFIED: No error (import succeeded)\n - BATCH_IMPORT_ERROR_INVALID_ARGUMENT: The key data is malformed or missing required fields\n - BATCH_IMPORT_ERROR_ALREADY_EXISTS: A key with this identifier already exists\n - BATCH_IMPORT_ERROR_FAILED_PRECONDITION: State conflict prevents the import\n - BATCH_IMPORT_ERROR_INTERNAL: Server error during import",
+ "enum": [
+ "BATCH_IMPORT_ERROR_UNSPECIFIED",
+ "BATCH_IMPORT_ERROR_INVALID_ARGUMENT",
+ "BATCH_IMPORT_ERROR_ALREADY_EXISTS",
+ "BATCH_IMPORT_ERROR_FAILED_PRECONDITION",
+ "BATCH_IMPORT_ERROR_INTERNAL"
+ ],
+ "type": "string",
+ "title": "v2alpha1BatchImportErrorCode"
+ },
+ "error_message": {
+ "title": "Human-readable failure reason",
+ "type": "string"
+ },
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "expire_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportedAPIKey"
+ },
+ "index": {
+ "format": "int32",
+ "title": "Zero-based index in request.requests",
+ "type": "integer"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1BatchImportResult"
+ },
+ "type": "array"
+ },
+ "success_count": { "format": "int32", "type": "integer" }
+ },
+ "type": "object",
+ "title": "v2alpha1BatchImportAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Batch import completed. Check per-item results for individual status."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
index fd0bb12661..e7f021939c 100644
--- a/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-batch-import-api-keys.api.mdx
@@ -5,77 +5,34 @@ description: "Imports up to 1000 external API keys in one request. Returns per-i
sidebar_label: "Batch Import API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Imports up to 1000 external API keys in one request. Returns per-item
-results. If at least one item succeeds, response is 200 OK. If all items
-fail, the endpoint returns a non-200 error.
+Imports up to 1000 external API keys in one request. Returns per-item results. If at least one item succeeds, response is 200 OK.
+If all items fail, the endpoint returns a non-200 error.
-```http
-POST /v2alpha1/admin/importedApiKeys:batchImport
-{
- "requests": [
- {"raw_key": "sk_live_abc", "name": "Stripe key", "actor_id": "user_1"},
- {"raw_key": "ghp_xyz", "name": "GitHub PAT", "actor_id": "user_2"}
- ]
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
index 02f3db934e..7284320ed3 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.RequestSchema.json
@@ -1 +1,30 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"requests":{"items":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2alpha1VerifyAPIKeyRequest"},"type":"array"}},"type":"object","title":"v2alpha1BatchVerifyAPIKeysRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "requests": {
+ "items": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1VerifyAPIKeyRequest"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1BatchVerifyAPIKeysRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
index 2097ba0f0e..b4a72779a7 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.StatusCodes.json
@@ -1 +1,125 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"actor_id":{"type":"string"},"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"issuer":{"description":"The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.","type":"string"},"key_id":{"type":"string"},"metadata":{"type":"object"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1VerifyAPIKeyResponse"},"type":"array"}},"type":"object","title":"v2alpha1BatchVerifyAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "results": {
+ "items": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "issuer": {
+ "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
+ "type": "string"
+ },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1VerifyAPIKeyResponse"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1BatchVerifyAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
index 4a3e646ee6..09f2630c53 100644
--- a/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-batch-verify-api-keys.api.mdx
@@ -5,77 +5,34 @@ description: "Verifies multiple credentials in a single request. Efficiently ver
sidebar_label: "Batch Verify API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Verifies multiple credentials in a single request. Efficiently verifies up
-to 100 credentials in parallel. Each credential is verified independently;
-partial failures are returned. Admin access only.
+Verifies multiple credentials in a single request. Efficiently verifies up to 100 credentials in parallel. Each credential is
+verified independently; partial failures are returned. Admin access only.
-```http
-POST /v2alpha1/admin/apiKeys:batchVerify
-{
- "requests": [
- {"credential": "sk_live_abc123..."},
- {"credential": "eyJhbGciOiJFZERTQSI..."}
- ]
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
index 2a18929b0d..092cc31162 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
index 976062bed3..cd80ba989c 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.StatusCodes.json
@@ -1 +1,36 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"Imported key deleted successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "Imported key deleted successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
index 6d34b16714..6ca7bfa1a7 100644
--- a/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-delete-imported-api-key.api.mdx
@@ -5,70 +5,34 @@ description: "Permanently deletes an imported key (hard delete). The key is remo
sidebar_label: "Delete Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: eJzdVdtu5DYM/RWCT5lAyWSn3T74qYMmQGe3RdNcsA9J0CgWPdZGlrwSPbvGwEA/ol/YLykozySTC4rmtU++SCQPD8nDNRpKZbQt2+CxwFOKjfbk2fVgyBFTAu3BNm2ITAbuqYe9WkezOZ0cwkVN+bdNEKkJKzJQxdBce64JjGZ9pxMdwmUiOKNVuKf56eIj9VCFCClUPHqywcNepDI0DXlDZnJ47a/97e1tzdxe++OTX04uTmC6mmnX1vrdVJvG+ukW17y1H6lP0/U99X9YM2RLVBhailp8LwwWOBeb44x7sTXMWFBhq6NuiCkmLK7Wz1g5/3n+/t1sOnv/A9Q61RAqkOSesnJ28vvl4uzkeIIKrVi1mmtU6HVDWOCIDBVG+tLZSAYLjh0pTGVNjcZijdy3cjNxtH6Jw3Ajl1MbfKIk57OjI3mUwTN5llfdts6WOcPp5yRY1y/9hbvPVDIOw6Ce5TWH1JUlpVR1DrahDnFQODv6/i2hXvG92CVnbBazE871OY6hSneO35RWG6WsbEdSymBInlWIjWYs0Hr+boZqm731TEuKYzDW1mUry9TkF22MlTjane66HdSzMD+O7l4WST2jWSFbdvKjjYHDXVfNfY+P13SMOn83lJJevtFnbMtz1tylV8vpofP0raVSuKYYQ9ytqrjVS+lvFB+2/CmSIc9Wu4Q3AojrIHMyVisPBddY4H+dutz4VZCMngL7LfZwoV1IIhIaarusD1qKuWS+JEgZDpQPeKDRXi+pIc+QKK5sSYewYKi1N45Snj5pol0TZysq+9JRATalzvqltF5SsKJoq16+uaYGNIMLX8FpJl/2CgxFu5LTVIfIB86KgnG4J59g78OnC9DewK+61DEEP1H5M4qQiY3O/Zy1SnRwfrqQFFPrLIP1HIC/hm0GqZBrB7C//4L+/X34+8+/INMLD6KVijw8D4nBniRGCmJgzfLMeqo2QrRJhTbgFXz49PF8kvFmCjYTtYFArjofcW2CJ3LVwQZq9jxezzq9Q3MdnBGVfOzJx+rOTxeocEUxjXXf9o20exsSNzqP8kYRRyWGB6EQ8kYxftI9O8rwf1tPmyln+sbT1mnrhaguuqxyefauHjlUmJ3KkD11iwqLzXa5UViHxGK3Xktil9ENg/z+0lHssbi6UbjS0eo7KZ0sOpvk3WBRaZfoX7jfO9ssrgm8eR++muhWEL2UfKVdJ1+oZFM+7svhZlBYkzYUM97xcF6W1PKO2YuNMewK2lgeHIZ/ANhyIPw=
+api: eJzNVu9u2zYQf5XbAQPsgLbbbN0HDQVmNMHmdsO8JEU/1EHBSCeLDUWq5MmJYQjYQ+wJ9yTDUUpiJ92AfBsggKTI+/e74++4w4JiHkzDxjvMcEmh1o4c2y0UZIkpgnZg6sYHpgKuaQujSodi2B1P4aKi9NtECFT7DRVQBl+vHFcEhWZ9pSNN4X0kOKONv6b5cvGOtlD6ANGX3Gsy3sEoUO7rmlxBxXiKCn1DQcvWosAM50Vt3Ekyuxj86VWhwkYHXRNTiJh93D0K6vyX+auXx7PjVz9ApWMFvgTx7TCos9M/3i/OTk/GqNCIVKO5QoVO14QZXtP2kylQYaAvrQlUYMahJYUxr6jWmO2Qt42cjByMW2PXXcrh2HgXKcr+8YsXMuTeMTmWqW4aa/IU4exzFF93T/X5q8+UM3Zdpx7FNYfY5jnFWLYW7kxNsVN4/OL755j6iu7FPjh9ros9c3ab7BRU6tbys8JqgqSVTQ9K7guSsfSh1owZGsffHaO6i944pjWF3hhrY5OUYarTRBeFETvaLvfVduqRmZ96dU+TpB7BrJANW/nRBM/+qi3nbosPx3QIOq1rilGvn6kzNPk5a27jV9PpoHV021AuWFMIPuxnVdTqtdQ3ig6TvwlUkGOjbcRLhbcTwfJc142l/hZY7daY4dqjQquvyGKGP8si+jbkCd2UZRit3IpXfQpveYX9sqz7qVtxbg05hhWuDVft1TT39cyH7Yy19XHS707WXo6PRaJsXT5UzeFVHeV8C4Od6Zt+VJDDUa9jOl8u3qSZksJbnEAP6niAYyfOmBI+KfkoBMheQz59gsd8uZimIPhfSUM8GYyMh7Ont5S3TKPxj0n1N6/BGdvbXHEgboODsubpqfhSjlbYR3hAJBl8e7PC5JsgwV0PoIgtg3Fs3WiFJ8N9OhAUqd4dERjMOWNXrkPhkpq48sKDvdVEelxhhrPNsbZNpV/OtAQ7u9M6b8w72sbZrueuLhFb6aViDwvv97CFC8mkcLiGyqyrSUMhXUmXE8QEL+T3+EKtnV5TLTURKWxMTlNYMFTaFZZiYlchiX0Ra0rKt7mlDEyMrXFriTYq2FAw5VbWXFENmsH6G7CayeVbBQUFs5HdWPnAE2ukwbC/Jhdh9PbDBWhXwG8618F7N1ZpGaTPiIxOfCXpddKm5suFhBgbaxiMYw984+8iiJkcm8DR0ZNyOjqCv//8CxK8cN+UYpbI8T4wGElgpCB41ixjandqSPMQCg3OK3j74d35OPmbIBgYc3CBbHne+zUYj2TLyeBq0twfT210D+bK20K64APnPGR3vlygwg2F2Of9rm6EzhofudaJqoeO1xcp3DcCAa9vtgfVs8f8/7PXw0DCQjGzxmrjJM422NSE0tX5+ACBwpRduSOH1wcVZkPzv1RY+cgit9uJX++D7Tr5/aWlsMXs46XCjQ5GXwny8g4xUeYFZqW2kf4DutHZ8K4Yw7OfK18N9K5fOcnYRttWVqjkIfPwnOkuO4UV6YJC8rffnOc5Nbwn9qShH/DRyemvpxen2HX/AJB1mfo=
sidebar_class_name: "delete api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Permanently deletes an imported key (hard delete). The key is removed from
-the database. Use RevokeAPIKey for soft deletion (recommended).
+Permanently deletes an imported key (hard delete). The key is removed from the database. Use RevokeAPIKey for soft deletion
+(recommended).
-```http
-DELETE /v2alpha1/admin/importedApiKeys/{key_id}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-derive-token.RequestSchema.json b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
index c96fb965ed..0fecc60986 100644
--- a/docs/talos/reference/api/admin-derive-token.RequestSchema.json
+++ b/docs/talos/reference/api/admin-derive-token.RequestSchema.json
@@ -1 +1,38 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"algorithm":{"default":"TOKEN_ALGORITHM_UNSPECIFIED","description":"- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)","enum":["TOKEN_ALGORITHM_UNSPECIFIED","TOKEN_ALGORITHM_JWT","TOKEN_ALGORITHM_MACAROON"],"title":"TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken","type":"string"},"credential":{"title":"The API key secret (issued or imported) to derive a token from","type":"string"},"custom_claims":{"type":"object"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"}},"title":"Token derivation messages","type":"object"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "algorithm": {
+ "default": "TOKEN_ALGORITHM_UNSPECIFIED",
+ "description": "- TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed)\n - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)",
+ "enum": [
+ "TOKEN_ALGORITHM_UNSPECIFIED",
+ "TOKEN_ALGORITHM_JWT",
+ "TOKEN_ALGORITHM_MACAROON"
+ ],
+ "title": "TokenAlgorithm specifies the cryptographic algorithm used for derived tokens\nNote: API keys (root tokens) are always opaque; this enum is only for DeriveToken",
+ "type": "string"
+ },
+ "credential": {
+ "title": "The API key secret (issued or imported) to derive a token from",
+ "type": "string"
+ },
+ "custom_claims": { "type": "object" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ }
+ },
+ "title": "Token derivation messages",
+ "type": "object"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-derive-token.StatusCodes.json b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
index 167b2a0766..a575b397b0 100644
--- a/docs/talos/reference/api/admin-derive-token.StatusCodes.json
+++ b/docs/talos/reference/api/admin-derive-token.StatusCodes.json
@@ -1 +1,51 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"token":{"properties":{"claims":{"type":"object"},"expire_time":{"format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"token":{"type":"string"}},"title":"Token represents a short-lived derived token (JWT or Macaroon)","type":"object"}},"type":"object","title":"v2alpha1DeriveTokenResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "token": {
+ "properties": {
+ "claims": { "type": "object" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "token": { "type": "string" }
+ },
+ "title": "Token represents a short-lived derived token (JWT or Macaroon)",
+ "type": "object"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1DeriveTokenResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-derive-token.api.mdx b/docs/talos/reference/api/admin-derive-token.api.mdx
index 56d2d8a202..d2d4b74c45 100644
--- a/docs/talos/reference/api/admin-derive-token.api.mdx
+++ b/docs/talos/reference/api/admin-derive-token.api.mdx
@@ -5,75 +5,34 @@ description: "Mints a short-lived JWT or Macaroon token from an API key. Works w
sidebar_label: "Derive Token"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Mints a short-lived JWT or Macaroon token from an API key. Works with both
-issued and imported keys. The derived token inherits the permissions of the
-parent API key.
+Mints a short-lived JWT or Macaroon token from an API key. Works with both issued and imported keys. The derived token inherits
+the permissions of the parent API key.
-```http
-POST /v2alpha1/admin/apiKeys:derive
-{
- "credential": "eyJhbGciOiJFZERTQSI...",
- "ttl": "1h"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
index 2a18929b0d..092cc31162 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
index 7c2e8fbd5b..04385063bd 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-imported-api-key.StatusCodes.json
@@ -1 +1,125 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-imported-api-key.api.mdx b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
index 96186e7886..2085b100cd 100644
--- a/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-get-imported-api-key.api.mdx
@@ -5,70 +5,33 @@ description: "Retrieves details about a specific imported key. Returns metadata
sidebar_label: "Get Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Retrieves details about a specific imported key. Returns metadata about
-the imported key. The original raw key is never returned.
+Retrieves details about a specific imported key. Returns metadata about the imported key. The original raw key is never returned.
-```http
-GET /v2alpha1/admin/importedApiKeys/{key_id}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
index d3b3282f04..ab64880579 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"UUID of the issued key, taken from the path\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "UUID of the issued key, taken from the path\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
index fa372beabf..e0def4fa1b 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-issued-api-key.StatusCodes.json
@@ -1 +1,125 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-issued-api-key.api.mdx b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
index 8c6c6fe50c..72ad173dfb 100644
--- a/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-get-issued-api-key.api.mdx
@@ -5,70 +5,34 @@ description: "Retrieves details about a specific issued API key including its st
sidebar_label: "Get Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Retrieves details about a specific issued API key including its status,
-scopes, expiration, and usage statistics. The secret is never returned.
+Retrieves details about a specific issued API key including its status, scopes, expiration, and usage statistics. The secret is
+never returned.
-```http
-GET /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-get-jwks.RequestSchema.json b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
+++ b/docs/talos/reference/api/admin-get-jwks.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-get-jwks.StatusCodes.json b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
index 37773d0b3d..d276273964 100644
--- a/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
+++ b/docs/talos/reference/api/admin-get-jwks.StatusCodes.json
@@ -1 +1,42 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"jwks":{"title":"JSON Web Key Set","type":"object"}},"type":"object","title":"v2alpha1GetJWKSResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "jwks": { "title": "JSON Web Key Set", "type": "object" }
+ },
+ "type": "object",
+ "title": "v2alpha1GetJWKSResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-get-jwks.api.mdx b/docs/talos/reference/api/admin-get-jwks.api.mdx
index c488c5db43..ca0847429d 100644
--- a/docs/talos/reference/api/admin-get-jwks.api.mdx
+++ b/docs/talos/reference/api/admin-get-jwks.api.mdx
@@ -5,64 +5,30 @@ description: "Returns the JSON Web Key Set for token verification. Provides the
sidebar_label: "Get JWKS"
hide_title: true
hide_table_of_contents: true
-api: eJztVdtu4zYQ/ZUBn5JAsXfTywJ6arDYDZJFu0GcRR7iABmTI4sJRarkyFnBMNCP6Bf2S4qh5NhJi6KLvvaJlMRz5sxw5mitDCUdbcs2eFWqK+Iu+gRcE1zMPv8CN7SAT9TDjBiqEIHDI3lYUbSV1SioCVzGsLKGBlTbLZzVc/9IfQJPZMgAhwHRw8XN9UCRwKbUkYFFD1zbBIniymqaSLQEGAlcQENm7qsYGtDBV3bZxRwSDirrqJxOC6iZ25R3IcICE/34fTmdwper83Q4gY/BufCUhc39xc2nGSRGbzAaOLj6+B7e/fD23eFk7uf+/v5eqOb+7MM1TFcn6Noa307RNNZPDUW7IiPKpg9Pj2nykMKAUYUKLQ2qzo0q1akAzoglmCpUpNQGnyipcq1O3ryRRQfP5Fm22LZuLONUOOVd0jU1KLs2CjfbAS2BZWXLjlSpXl+PKhT3rXwJiwfSrDab12+KZ/A2wVHp1ShTbQT0siVOIXVaU0pV52Cbz0TlcxV2jv9DTjoYkrUKsUFWpbKevzvZZWI905LiEIzRuoyyTE3eoDFW4qC73KfdFK/C/DTQrbe0iaP1y38sUBsDh0VXnfpe7Y5hjJifG0oJl9/IGVs9Y+Qu/W2ZPXSevrakmQxQjCHuV1tocZlUeauEw+r3kQx5tuiSuhNBXAdpwGXuhBa5VqX6V42sCmV9FSSXl5I+xx6u0QWZVUCo7bI+binmy/KaZJbYatDPSqBBj0tqyPNuns8ZavTGjf5Qdc7tQ5ytSPfaUZkdwfoliHUUo2PIM9fUADK48AQOmbzuC8ipyNdUh8jHTvLaWsuB2Ax6Az+jxhiCPyzyY6RVeBQM5obOg39dE5xenkuKqXWWwXoOwE9hm0Eq5dgxHB39pfBHR/DHb79Dri08+0AqJYNdYnCQra6AGBhZVpFBBdimDZHHVGgUX4AM5GHWu2+zowRy1WzQNQZP5KrjUWpmHo5ns94rcx2coZj2unF3u6eX56pQK4ppuPdt00ijtyFxg3mIPTaCOyOG0d1etMueCfz/G/n238hoGkxfedo6tF6q30WXTTNP8+3uYgqVGfMVPHOqQu1m+q5QdUgsqPVaEvoS3WYjr3/tKPaqvL0r1AqjxYV0w+3dplA1oaGoytu1eqRePElrasVOVui67H+vvX2zbz1nH67VZvMnSYXpAg==
+api: eJzlVm1r3EYQ/ivTgcKdke+S9CUgCPQwiTmHNMZ2yAfLhL3VSNp4tavujs4+joP+iP7C/pIyK519dkqh9GM/7Yt23p6ZeUZbLCnqYDo23mGOF8R9cBG4ITi7/PgrfKYVvKcNXBJD5QOwvyUHawqmMlqJ1AzOg1+bkgaprl9Zowt3S5sIjqikEtgPEhs4+3w1qIhgYuyphNUGuDERIoW10TQTaxFUILBelVQWrgq+Be1dZeo+JJMwqYylfD7PoGHuYtr5ACsV6ecf8/kcPl0s43QG77y1/i45Vrizz+8vIbJypQolTC7encDrn16+ns4wQ9/RoHpZYo6LsjXulFgkMMNAsfMuUsR8i69evJBFe8fkWLaq6+yIxfxrFBi3GHVDrZJdF0Q3m0H6691tWtmwJczxOcaYIW86+eJXX0kz7nbPb7IH4fUrZbtGvRw9vRjdxJ0IPc3rAmKvNcVY9Rb28cwwvatUb/k/xKR9SbJWPrSKMUfj+IdXj5EYx1RTGIyxMjZJGaY2bVRZGrGj7Pmh2l32zMwvg7rtXm3kYFz9jwB1wbNf9dXCbfDxmQpBpXNLMar6X+oMnb5kxX38W5gd9I7uO9JMJVAIPhyiLWpVHTG/RtFh9EmgkhwbZSPeZHh/LFheqrazEvP1Fq1yNeZYe8zQqhVZzPFUDtH3QSd0284HhknhCi6GFN5zgcORnPalcXXK4f6yaofvrmBtDTmGAmvDTb+aad/OfdjMWVkfj4evx7WX51ORqHqnoR7KbaL5HkZ7s5NhzUDD0SA2W5wvT9JuOgKxFYuCRgZfMrmD/A3o2TdILM6Xs+QpH/ahmJuO92/vSfdME/GJTZV0ffcGnLGDETEjPAZVy7O3YryaFFgTg2jK4fu7ApMHScFuwEJYI9LAfMIUT0grgq8qaxwlD3zPGXwR9wXX2QcVYqPs0kkEE4lwdnZ3GzMoUOwUCFBgMiX+nAfj2LrJUGsT3/N0OiCTXHbGFm6HuxupT2688FGdiKFT3GCO833bz5XAMy8pmDWVQptzoZdZ6tcMjau8lPbTCv0YNnAl2QUTQUFj6ua4o5B612kSfmSjQT+kA1rlVE2t1MkDRy8ZGuVKO3J+1Vt7KGJNRXqjLeWJ5Y2rQcZBNgIqZ26oBcVg/R1YxeT0JoMUinyNjQ98bCWu/biYyOhQroQPSqvgvZtm6Rho7W9FRiV+k/y4q4Zgcb6UEGNnDYNx7IHv/D6CmMuzYzg6+qb6jo7gz9//gIQtPIyFmEsEj4HBJI2vDIJnxbKKG5TB0I5jKDQ6n6WKmiZ/D0fn6ALZ6nLwazQeyVbHo6tJ8/A8DeADmBtvSwrxgJwes7s4X2KGawpxyPu+aIT3Oh+5VYnTnWpF7nRsDXxGaAcz4X/7azAOAqG3eWeVcQJhH2wahKklrx/RzTAVTsLxoS0xw8fGvMmw8ZFFarsVrz4Fu9vJ9W89hQ3m1zcZrlUwaiUpvb7ZZdiQKimkgXBLG5kzWlMnnLBWtk8z7fm8fsIfp2+vcLf7C0hBdG0=
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
-
-
+
-
-
-
+
+Returns the JSON Web Key Set for token verification. Provides the public keys needed to verify JWT tokens issued by this service.
+Keys are loaded from configuration (file://, https://, or base64:// URIs). Follows the JWKS standard (RFC 7517).
+
-Returns the JSON Web Key Set for token verification. Provides the public
-keys needed to verify JWT tokens issued by this service. Keys are loaded
-from configuration (file://, https://, or base64:// URIs). Follows the
-JWKS standard (RFC 7517).
+
-```http
-GET /v2alpha1/admin/derivedKeys/jwks.json
-```
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-import-api-key.RequestSchema.json b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
index 23a8a35c96..89924c2511 100644
--- a/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-import-api-key.RequestSchema.json
@@ -1 +1,91 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","properties":{"actor_id":{"description":"actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"Additional metadata (OPTIONAL)","type":"object"},"name":{"title":"Human-readable name (REQUIRED)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"raw_key":{"title":"The actual key string to import (REQUIRED)","type":"string"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"title":"Scopes for the imported key (OPTIONAL)","type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"title":"ImportAPIKeyRequest imports an external HMAC-based API key","type":"object"}}},"description":"Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "properties": {
+ "actor_id": {
+ "description": "actor_id is the identifier of the entity that owns this imported key.\nRequired so every imported key is traceable to an actor for revocation and\naudit queries.",
+ "type": "string"
+ },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": {
+ "title": "Additional metadata (OPTIONAL)",
+ "type": "object"
+ },
+ "name": {
+ "title": "Human-readable name (REQUIRED)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "raw_key": {
+ "title": "The actual key string to import (REQUIRED)",
+ "type": "string"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "Scopes for the imported key (OPTIONAL)",
+ "type": "array"
+ },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "title": "ImportAPIKeyRequest imports an external HMAC-based API key",
+ "type": "object"
+ }
+ }
+ },
+ "description": "Example:\n {\n \"raw_key\": \"sk_live_abc123xyz789\",\n \"name\": \"Stripe Production Key\",\n \"actor_id\": \"payment-processor\",\n \"scopes\": [\"read\", \"write\"],\n \"ttl\": \"8760h\", // 1 year (also accepts: 31536000s)\n \"metadata\": {\"source\": \"stripe\", \"environment\": \"production\"}\n }",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-import-api-key.StatusCodes.json b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
index 180fa3c667..bcac8f1cd6 100644
--- a/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-import-api-key.StatusCodes.json
@@ -1 +1,135 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_key":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}},"type":"object","title":"v2alpha1ImportAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key imported successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_key": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportedAPIKey"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key imported successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-import-api-key.api.mdx b/docs/talos/reference/api/admin-import-api-key.api.mdx
index 3c099bbdca..949fa5427c 100644
--- a/docs/talos/reference/api/admin-import-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-import-api-key.api.mdx
@@ -5,77 +5,35 @@ description: "Imports an external API key into the system. Allows importing keys
sidebar_label: "Import API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Imports an external API key into the system. Allows importing keys from
-legacy systems or external providers. The raw key is hashed with
-SHA-512/256 and only the hash is stored — the raw key is never retained.
-Imported keys support token derivation (JWT/Macaroon) like issued keys.
+Imports an external API key into the system. Allows importing keys from legacy systems or external providers. The raw key is
+hashed with SHA-512/256 and only the hash is stored — the raw key is never retained. Imported keys support token derivation
+(JWT/Macaroon) like issued keys.
-```http
-POST /v2alpha1/admin/importedApiKeys
-{
- "raw_key": "sk_live_abc123xyz",
- "name": "Imported Stripe Key",
- "actor_id": "user_123"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
index 8025b5c876..104d67e4ab 100644
--- a/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-issue-api-key.RequestSchema.json
@@ -1 +1,72 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"request_id":{"title":"Client-controlled idempotency key (AIP-155)","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"ttl":{"description":"ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssueAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "request_id": {
+ "title": "Client-controlled idempotency key (AIP-155)",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "ttl": {
+ "description": "ttl sets the expiry as a duration from now.\nAccepted formats:\n - Extended: \"1y\" (365d), \"1mo\" (30d), \"1w\" (7d), \"1d\" (24h)\n - Standard Go: \"24h\", \"30m\", \"60s\", \"1h30m\"\n - Compound: \"1y6mo\", \"1d12h\", \"2w3d\"\nApproximations: 1y = 365 days, 1mo = 30 days.\nIf unset, the project default TTL applies. Maximum is ~10 years (315360000s).",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssueAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
index 2d3f09ef04..c5a226f0b3 100644
--- a/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-issue-api-key.StatusCodes.json
@@ -1 +1,139 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"secret":{"title":"Only returned on creation","type":"string"}},"type":"object","title":"v2alpha1IssueAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key issued successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ },
+ "secret": {
+ "title": "Only returned on creation",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssueAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key issued successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-issue-api-key.api.mdx b/docs/talos/reference/api/admin-issue-api-key.api.mdx
index efce5124b5..b6a5a1095a 100644
--- a/docs/talos/reference/api/admin-issue-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-issue-api-key.api.mdx
@@ -5,77 +5,34 @@ description: "Creates a new API key for a given actor. The secret is returned on
sidebar_label: "Issue API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Creates a new API key for a given actor. The secret is returned only once
-in the response and cannot be retrieved later. Keys can be scoped with
-specific permissions and have optional expiration.
+Creates a new API key for a given actor. The secret is returned only once in the response and cannot be retrieved later. Keys can
+be scoped with specific permissions and have optional expiration.
-```http
-POST /v2alpha1/admin/issuedApiKeys
-{
- "name": "production-service",
- "actor_id": "user_123",
- "scopes": ["read", "write"],
- "ttl": "8760h"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
index 3a777c3e7d..76d4d28b3c 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.ParamsDetails.json
@@ -1 +1,22 @@
-{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination (OPTIONAL)","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination (OPTIONAL)",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
index 14fa61109c..52b6644878 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.StatusCodes.json
@@ -1 +1,145 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"imported_api_keys":{"items":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"},"title":"List of imported keys","type":"array"},"next_page_token":{"title":"Token for fetching the next page (empty if no more results)","type":"string"}},"title":"ListImportedAPIKeysResponse returns paginated list of imported keys","type":"object"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "imported_api_keys": {
+ "items": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportedAPIKey"
+ },
+ "title": "List of imported keys",
+ "type": "array"
+ },
+ "next_page_token": {
+ "title": "Token for fetching the next page (empty if no more results)",
+ "type": "string"
+ }
+ },
+ "title": "ListImportedAPIKeysResponse returns paginated list of imported keys",
+ "type": "object"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
index d20394cbe0..81af39280d 100644
--- a/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-list-imported-api-keys.api.mdx
@@ -5,70 +5,34 @@ description: "Lists all imported keys with filtering. Returns imported keys only
sidebar_label: "List Imported API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Lists all imported keys with filtering. Returns imported keys only (not
-issued keys). Supports pagination and AIP-160 filter expressions.
+Lists all imported keys with filtering. Returns imported keys only (not issued keys). Supports pagination and AIP-160 filter
+expressions.
-```http
-GET /v2alpha1/admin/importedApiKeys?page_size=50&filter=status%3DKEY_STATUS_ACTIVE
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
index e8f3ff5027..4a5e5fb847 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.ParamsDetails.json
@@ -1 +1,22 @@
-{"parameters":[{"description":"Number of items per page (default: 50, max: 1000)","in":"query","name":"page_size","schema":{"format":"int32","type":"integer"}},{"description":"Cursor token for pagination","in":"query","name":"page_token","schema":{"type":"string"}},{"description":"filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE","in":"query","name":"filter","schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "Number of items per page (default: 50, max: 1000)",
+ "in": "query",
+ "name": "page_size",
+ "schema": { "format": "int32", "type": "integer" }
+ },
+ {
+ "description": "Cursor token for pagination",
+ "in": "query",
+ "name": "page_token",
+ "schema": { "type": "string" }
+ },
+ {
+ "description": "filter supports AIP-160 filter expressions:\n actor_id=\"user_123\"\n status=KEY_STATUS_ACTIVE\n actor_id=\"user_123\" AND status=KEY_STATUS_ACTIVE",
+ "in": "query",
+ "name": "filter",
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
index c96bcede2f..e9fcb6db7c 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.RequestSchema.json
@@ -1 +1 @@
-{"title":"Body"}
\ No newline at end of file
+{ "title": "Body" }
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
index 4560c5eee2..533d4a3307 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.StatusCodes.json
@@ -1 +1,141 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_keys":{"items":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"type":"array"},"next_page_token":{"type":"string"}},"type":"object","title":"v2alpha1ListIssuedAPIKeysResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_keys": {
+ "items": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "type": "array"
+ },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ },
+ "type": "array"
+ },
+ "next_page_token": { "type": "string" }
+ },
+ "type": "object",
+ "title": "v2alpha1ListIssuedAPIKeysResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
index 6295f1f64f..803470832c 100644
--- a/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
+++ b/docs/talos/reference/api/admin-list-issued-api-keys.api.mdx
@@ -5,71 +5,34 @@ description: "Lists issued API keys with optional filtering. Supports cursor-bas
sidebar_label: "List Issued API Keys"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "get api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Lists issued API keys with optional filtering. Supports cursor-based
-pagination and AIP-160 filter expressions. Returns only issued
-(generated) API keys; use ListImportedAPIKeys for imported keys.
+Lists issued API keys with optional filtering. Supports cursor-based pagination and AIP-160 filter expressions. Returns only
+issued (generated) API keys; use ListImportedAPIKeys for imported keys.
-```http
-GET /v2alpha1/admin/issuedApiKeys?page_size=50&filter=actor_id%3D%22user_123%22
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
index 02cd67dfcd..ff4e18118e 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"Identifier of the key to revoke, taken from the path\n(`POST /v2alpha1/admin/apiKeys/{key_id}:revoke`). For issued keys this is\nthe UUID; for imported keys this is the SHA-512/256 hash. REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "Identifier of the key to revoke, taken from the path\n(`POST /v2alpha1/admin/apiKeys/{key_id}:revoke`). For issued keys this is\nthe UUID; for imported keys this is the SHA-512/256 hash. REQUIRED.",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
index 61224ec4e1..faff6de104 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.RequestSchema.json
@@ -1 +1,34 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"description":{"description":"Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"}},"type":"object","title":"StaticCredentialsAdminRevokeAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "description": {
+ "description": "Optional free-text explanation. Only allowed when reason is PRIVILEGE_WITHDRAWN.",
+ "type": "string"
+ },
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminRevokeAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
index f7e1bfaac2..d3cec6dad6 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-revoke-api-key.StatusCodes.json
@@ -1 +1,36 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A successful response."},"204":{"content":{"application/json":{"schema":{}}},"description":"API key revoked successfully."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": { "application/json": { "schema": { "type": "object" } } },
+ "description": "A successful response."
+ },
+ "204": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key revoked successfully."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-revoke-api-key.api.mdx b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
index c0325d307d..354b458248 100644
--- a/docs/talos/reference/api/admin-revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-revoke-api-key.api.mdx
@@ -5,74 +5,34 @@ description: "Immediately revokes an API key (issued or imported). Once revoked,
sidebar_label: "Revoke API Key"
hide_title: true
hide_table_of_contents: true
-api: eJydVtty2zYQ/ZUdPMUeSnbcppOyL1VsOWacWLIkx7kwY0PkUkQMAiywlM3xaKYf0S/sl3QA0rIsKU3TB40IcrHXc3b3nqVoEyNKElqxkEVFganghLIGg3N9gxa4gt4wghus4ZmwtsIUtAFRlNoQpjtdGKgEW+k0AMrRycYq4QqUBqnVDA1MESqLKWTaAK8oR0Ui4c5sFya5sKBLNP4MwoIwBudorJhK7MZq1Ch3ei1w46wRF2qpLhUEZWVKbdF2YxWr6+vrnKiM1XAwnsDe/IDLMufP93haCLXHS3GKtd3bf35y/unDr+8/np++efXyw/mn8+b34TxswonVfawAYmaQW61iFkLMRv33g8PeJBqcXY36vfHg7Oq0//HqcPBuOBq8i8b9mMVq4V1gAVtGFaUsZD1nvgmmN4xOsWYBK7nhBRIay8LP9+v1SF2eMoEGdPaQWiDdpjsA4jeoIDO68F9LTnmsnl3/a9j3N1hfiXTRBnm904VjV9Gmtj7H5CoibKyc0ouL6Og3n+mHoj8R8obHJ73Oi+cHewcvfoGc27wLo/75RTTqH3VZwISLxfnGAqZ4gSxkjQ8sYAb/qITBlIVkKgyYTXIsOAvvGdWlk7RkhJqxxeJLI4yWXum0dhKJVoSK3CMvS9kCau+rdcm7X1FVGlcIEmjd6UmO11M+8A9cQmYQO4R3BHhXSq5asA6UrIFLqW8xhdscFTTgcJkYjqL30dv+6/7VZTQ5ORr1Ls9c+GuBBC2cGtsZrySxcAusLs7Gw/5hdBz1j1iw5qUDURPtqLFeGj0XKVqwZKqEKoOpB0kj1PpoQShbumzDtIbR8SG8OHi5343VhaOmUDDVlINHC3CVgkWZdVa0ZFLfNgSDDmw6vCX8EDzmO1rJOgSlaZk6odbVs4ChqgoWfv5uMr7Hwa0ivePj6G3UvDo86Z29/oaq8cWwPxr3j77xeUuU7Mt6kQNGgqR78UDC9YqxxWJ5SU+/YkIrl8bESSSHBj3/ubQbncNTYLFYbBLorqONmAnF5dC1lrOGb1Mv76RtqZVtiHCwv/9DNHrqrrf+FJY9sFWSoLVZJeHBVNfZPdj/+UdMbdPdDqF20qxYkrU3seTS/24MiU7R/WfaFNyRUij66eCRwUIRztA0xogL6W8JwsI/8DQVTfMYrqpdBGtmfm/UbXa4bwOiNJr0tMp6ylexFePGcH8u0Fo++0Gdpkwcziq7tZIKKoV3JSau36Mx2qwW1KnlMzeyNrHq2FAg5dqNvFJb8lOOchay/ziSWMBcqUaP3b5/x4tS4ma7XvLtoad+p3cs3DTK9Ja+b2qYcKn9SOOQi1neKdF4KLgFx/owIVnGCQVXfIYFKgKLZi4S7EJEkHOVSmzGogPn6hUpMkzqRGLox61QMz9KA5ijEVntzpRjAZxA6luQnFAldQApGjF3X22uDXWkmGMKpG9QWXj25nLiu/U7nnCjtdoJ/NGn0t3hnie+bU9y9MucsGBLKQiEIg10qx8isKET68Du7kZZd3fh7z//aqfDcq+xoSflMrB2RwzAaOLk/ttNpdkd2lCwdT6AN5en4x3vr09By9TWBZTZuPGrNe4nRuvq6nhzy8lKmnMtU7dQPWL9sbq9YcQC5pdLX/cHRLLF4h/QvNbf
+api: eJydV41u2zYQfpUbgQ1OIDtttg6DigLzEqdR08aenTQYqiKlpZPFhSI18pTYCAzsIfaEe5KBpOw4doq2AwxIFI/3fx8/37McbWZETUIrFrOkqjAXnFAuwOCtvkELXEF/lMANLqAjrG0wB21AVLU2hPleD4Yqw1Y6j4BKdLKpyrgCpUFqNUMDU4TGYg6FNsAbKlGRyLgz24OLUljQNRq/BmFBGIO3aKyYSuylahyUO70WuHHWiAu1VpcLgroxtbZoeyxia11JzmLWzyvRquiPkjNcsIjV3PAKCY1l8Yf77SzkzrtCoAFdrAIC0m2QERC/QQWF0ZXfrTmVqep8Gg0nF3Bwe8hlXfLnB9zZPeC1OMOFPbi/wcW1yJdxUPJprwcnLo8hoz4ycnkQNlVO6eVlcvzSx7dK9SMhb3hy2u++eH54cPjiZyi5LXswHvx+mYwHxy4LwsXifGMRU7xCFrPgA4uYwb8aYTBnMZkGI2azEivO4ntGi9pJWjJCzdhy+TEIo6XfdL5wEplWhIrcK69r2Zbx4E/rkne/oao2rhAk0LrVoxxvp3zoX7iEwiB2CecEOK8lV22LDJVcAJdS32EOdyUqMMhtaJbROHmfvB28HlxfJRenx+P+1bkLfysQFwa3K9sFbySxmI0H74dH/YtkeH49HvQnw/Pry/PJaHCUnCSDYxZteemaKEQ7DtZro29FjhYsmSajxmDumyQItT5aEMrWLtswXcD45AheHP7yrJeqSzcQQsFUUwm+W4CrHCzKoruhpZD6zvZSlSrowq7DT4Qfg+/5rlZyEYPStE6dUNvqWcRQNRWLP3wxGbv7Z4M/ro+G70bj4btkMnhSpH9ykrxNwqej0/7568+omlyOBuPJ4Pgz209EyT5uFzliJEi6D6sh3K4YWy7Xh/T0T8xo49CEOInsyKCffy7tDnL4EVgul7sDNO9qI2ZCcTly0HIe5m3q5Z20rbWyYRAOnz37pjF67K63/rgt+2CbLENri0bCylTP2T189tO3mHpKdwv9Lb5vWJILb2I9S/8bGDKdo3sW2lTcDaVQ9OPhwwQLRThDE4wRF9KfEoSVf+F5LgJ4jDbVLqMtM78GdbsI9/mGqI0mPW2KvvJVbMW4MdyvK7SWz75Rp6kz12eNfbKSChqF8xozh/dojDabBXVq+cxdWbu96qZh3nW5nPCqlhguNsnVjMVsplnEJJ+iZDF77RZWNybz2fW3C3RSlVIaSjinlIVlUYVXlVImBSqClM0Elc20l+nqQJvFAXGpbTfsdmfaie+5E0WjsrZrwux0MppDq793FJ4RZLAfzvb6o+TIv0Wu4ZJjCMnca9Nw75xoQT9+Be2h94f9t6PT/vMHwGjx4ktY5bSJAq4j90NjvM7eLgKMkp5PBe1ggYundXWvlfk6AOm0vn+d9H1QnVIAsBh+CEmIwvflyvZgjllD2Nl76cP57hUoIaE9bZAao6CoqDdw2Sw6KQu1cQHE8P1dynwaXOloGSrupEdGKJKqk7KWg8VOMAQdCuIVKyFTtWSOLFRIpXa0q9aWPNOiksXsK2kRi5iDi/ED4xjMfTvvUoY15q/u9S/cX0vHiAr9BPcwC7hwXezIBIdSzMpujcbDkaO21tcJsnWhoOKKz7By82DR3IoMe5AQlFzlEgM1cwC5eUSKArNFJjH2lE+omadzEdyiEcXCranECjiB1HcgOaHKFhHkaMSt27WlNtSV4hZzIH2DykLnzdWFZwzveMaN1mov8kufSneGe6z21OGiRE/jhQVbS0EgFGmgO72KwMZOrAv7+zt9ub8P//79T8tQ1tzaxv5iWAfW/juIwGji5J4tWw4I04aCrfMRvLk6m+x5f30K2tuidQFlMQl+tcY9a2ld3aRYjiBvpLnUMnek/gFvH6rbHyUsYv5vha/7qiPZcvkfK5qLgw==
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Immediately revokes an API key (issued or imported). Once revoked, the key
-can no longer be used for authentication. This operation is irreversible.
-Revoked keys are retained for audit purposes.
+Immediately revokes an API key (issued or imported). Once revoked, the key can no longer be used for authentication. This
+operation is irreversible. Revoked keys are retained for audit purposes.
-```http
-POST /v2alpha1/admin/apiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:revoke
-{
- "reason": "REVOCATION_REASON_KEY_COMPROMISE"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
index 05941f5ce6..f832c1b781 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"key_id is the ID of the existing API key to rotate","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "key_id is the ID of the existing API key to rotate",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
index 6cc8628ec3..7e0b94dc4a 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.RequestSchema.json
@@ -1 +1,77 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"title":"metadata for the new API key (inherits from old key if not provided)","type":"object"},"name":{"title":"name for the new API key (inherits from old key if not provided)","type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"title":"scopes for the new API key (inherits from old key if not provided)","type":"array"},"update_mask":{"title":"update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"StaticCredentialsAdminRotateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": {
+ "title": "metadata for the new API key (inherits from old key if not provided)",
+ "type": "object"
+ },
+ "name": {
+ "title": "name for the new API key (inherits from old key if not provided)",
+ "type": "string"
+ },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "scopes": {
+ "items": { "type": "string" },
+ "title": "scopes for the new API key (inherits from old key if not provided)",
+ "type": "array"
+ },
+ "update_mask": {
+ "title": "update_mask disambiguates \"not provided\" from \"set to empty\" (AIP-134)",
+ "type": "string"
+ },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminRotateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
index fd0c89e7b6..56f9fa53cb 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.StatusCodes.json
@@ -1 +1,229 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"old_issued_api_key":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"},"secret":{"title":"secret is the new API key secret (only returned once, never retrievable again)","type":"string"}},"type":"object","title":"v2alpha1RotateIssuedAPIKeyResponse"}}},"description":"A successful response."},"201":{"content":{"application/json":{"schema":{}}},"description":"API key rotated successfully. New key issued, old key revoked."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ },
+ "old_issued_api_key": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ },
+ "secret": {
+ "title": "secret is the new API key secret (only returned once, never retrievable again)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RotateIssuedAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "201": {
+ "content": { "application/json": { "schema": {} } },
+ "description": "API key rotated successfully. New key issued, old key revoked."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
index 9899c3ba2d..e318846ae2 100644
--- a/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-rotate-issued-api-key.api.mdx
@@ -5,80 +5,41 @@ description: "Generates a new secret for an issued API key. Creates a new API ke
sidebar_label: "Rotate Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Generates a new secret for an issued API key. Creates a new API key with a
-new key_id and secret, and immediately revokes the old key. This is the
-recommended way to update scopes, metadata, or rotate credentials.
+Generates a new secret for an issued API key. Creates a new API key with a new key_id and secret, and immediately revokes the old
+key. This is the recommended way to update scopes, metadata, or rotate credentials.
For zero-downtime rotation, use this workflow instead:
- 1. IssueAPIKey with new credentials
- 2. Deploy new secret to all services
- 3. Verify new secret works everywhere
- 4. RevokeAPIKey to remove the old key
-```http
-POST /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ:rotate
-{
- "scopes": ["read"]
-}
-```
+1. IssueAPIKey with new credentials
+2. Deploy new secret to all services
+3. Verify new secret works everywhere
+4. RevokeAPIKey to remove the old key
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
index 84eb488ec3..5881cc93c2 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"SHA512/256 hash of the imported key (REQUIRED, path param)","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "SHA512/256 hash of the imported key (REQUIRED, path param)",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
index 50adb4b243..699ee88f65 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.RequestSchema.json
@@ -1 +1,56 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"title":"AIP-134 partial update mask","type":"string"}},"type":"object","title":"StaticCredentialsAdminUpdateImportedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "update_mask": {
+ "title": "AIP-134 partial update mask",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminUpdateImportedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
index 7c2e8fbd5b..04385063bd 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-update-imported-api-key.StatusCodes.json
@@ -1 +1,125 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"title":"SHA-512/256 hash of credential","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1ImportedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "ImportedAPIKey represents an API key imported from an external system.\nThe raw key is hashed (SHA-512/256) and stored. The original key is never retained.",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "title": "SHA-512/256 hash of credential",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1ImportedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-imported-api-key.api.mdx b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
index c5de14cab0..afc393f48b 100644
--- a/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-update-imported-api-key.api.mdx
@@ -5,74 +5,33 @@ description: "Updates metadata, scopes, or rate limits of an imported key. Suppo
sidebar_label: "Update Imported API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "patch api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Updates metadata, scopes, or rate limits of an imported key. Supports
-partial updates via update_mask (AIP-134).
+Updates metadata, scopes, or rate limits of an imported key. Supports partial updates via update_mask (AIP-134).
-```http
-PATCH /v2alpha1/admin/importedApiKeys/{key_id}
-{
- "name": "New name",
- "update_mask": "name"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
index f561110464..258b044521 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.ParamsDetails.json
@@ -1 +1,11 @@
-{"parameters":[{"description":"UUID of the issued key to update, taken from the path\n(`PATCH /v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.","in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]}
\ No newline at end of file
+{
+ "parameters": [
+ {
+ "description": "UUID of the issued key to update, taken from the path\n(`PATCH /v2alpha1/admin/issuedApiKeys/{key_id}`). REQUIRED.",
+ "in": "path",
+ "name": "key_id",
+ "required": true,
+ "schema": { "type": "string" }
+ }
+ ]
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
index 1fa9ea943c..42ac28014d 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.RequestSchema.json
@@ -1 +1,53 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"scopes":{"items":{"type":"string"},"type":"array"},"update_mask":{"type":"string"}},"type":"object","title":"StaticCredentialsAdminUpdateIssuedAPIKeyBody"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "update_mask": { "type": "string" }
+ },
+ "type": "object",
+ "title": "StaticCredentialsAdminUpdateIssuedAPIKeyBody"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
index fa372beabf..e0def4fa1b 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-update-issued-api-key.StatusCodes.json
@@ -1 +1,125 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).","properties":{"actor_id":{"type":"string"},"create_time":{"format":"date-time","type":"string"},"expire_time":{"format":"date-time","type":"string"},"ip_restriction":{"description":"IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.","properties":{"allowed_cidrs":{"description":"allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).","items":{"type":"string"},"type":"array"}},"type":"object","title":"v2alpha1IPRestriction"},"key_id":{"description":"Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.","type":"string"},"last_used_time":{"format":"date-time","type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"revocation_description":{"description":"revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.","type":"string"},"revocation_reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"},"scopes":{"items":{"type":"string"},"type":"array"},"status":{"default":"KEY_STATUS_UNSPECIFIED","enum":["KEY_STATUS_UNSPECIFIED","KEY_STATUS_ACTIVE","KEY_STATUS_REVOKED","KEY_STATUS_EXPIRED"],"type":"string","title":"v2alpha1KeyStatus"},"update_time":{"format":"date-time","type":"string"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1IssuedAPIKey"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "IssuedAPIKey represents an API key issued (generated) by Talos.\nRoot keys are opaque v1 format tokens stored in the database.\nDerived tokens (JWT/Macaroon) are created via DeriveToken and are stateless (not stored).",
+ "properties": {
+ "actor_id": { "type": "string" },
+ "create_time": { "format": "date-time", "type": "string" },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "ip_restriction": {
+ "description": "IPRestriction defines IP-based access controls for an API key.\nWhen allowed_cidrs is non-empty, only requests from IPs matching at least one\nCIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed).\nIP restrictions apply to root API key and imported key verification only;\nderived tokens (JWT/macaroon) are stateless and not subject to IP checks.",
+ "properties": {
+ "allowed_cidrs": {
+ "description": "allowed_cidrs is a list of CIDR ranges that are allowed to use this key.\nSupports both IPv4 (e.g., \"10.0.0.0/8\") and IPv6 (e.g., \"2001:db8::/32\").\nIf empty, all IPs are allowed (no restriction).",
+ "items": { "type": "string" },
+ "type": "array"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IPRestriction"
+ },
+ "key_id": {
+ "description": "Server-generated UUID identifier for the issued key. Used as the path\nparameter on every admin endpoint that operates on this key\n(`/v2alpha1/admin/issuedApiKeys/{key_id}`). Stable for the lifetime of\nthe key; rotation produces a new key_id.",
+ "type": "string"
+ },
+ "last_used_time": { "format": "date-time", "type": "string" },
+ "metadata": { "type": "object" },
+ "name": { "type": "string" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "revocation_description": {
+ "description": "revocation_description provides free-form context for a revocation.\nOnly set when revocation_reason is PRIVILEGE_WITHDRAWN.\nJSON API change: field was formerly revocation_reason_text. Field number 13\nis unchanged so the change is wire-compatible for binary proto encoding.",
+ "type": "string"
+ },
+ "revocation_reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "status": {
+ "default": "KEY_STATUS_UNSPECIFIED",
+ "enum": [
+ "KEY_STATUS_UNSPECIFIED",
+ "KEY_STATUS_ACTIVE",
+ "KEY_STATUS_REVOKED",
+ "KEY_STATUS_EXPIRED"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyStatus"
+ },
+ "update_time": { "format": "date-time", "type": "string" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1IssuedAPIKey"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-update-issued-api-key.api.mdx b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
index f046df1542..189903de58 100644
--- a/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-update-issued-api-key.api.mdx
@@ -5,74 +5,34 @@ description: "Updates metadata, scopes, or rate limits of an issued key without
sidebar_label: "Update Issued API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "patch api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Updates metadata, scopes, or rate limits of an issued key without rotating
-the secret. Use RotateIssuedAPIKey to change the secret.
+Updates metadata, scopes, or rate limits of an issued key without rotating the secret. Use RotateIssuedAPIKey to change the
+secret.
-```http
-PATCH /v2alpha1/admin/issuedApiKeys/01HQZX9VYQKJB8XQZQXQZQXQXQ
-{
- "scopes": ["read"],
- "update_mask": "scopes"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
index ddf5c2ce0a..d1e2a98d5c 100644
--- a/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/admin-verify-api-key.RequestSchema.json
@@ -1 +1,21 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"properties":{"credential":{"title":"API key or derived token (any format: sk_*, JWT, macaroon)","type":"string"}},"type":"object","title":"v2alpha1VerifyAPIKeyRequest"}}},"required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "credential": {
+ "title": "API key or derived token (any format: sk_*, JWT, macaroon)",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1VerifyAPIKeyRequest"
+ }
+ }
+ },
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
index d0082d7018..4b415eba50 100644
--- a/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/admin-verify-api-key.StatusCodes.json
@@ -1 +1,113 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"type":"string"},"error_code":{"default":"VERIFICATION_ERROR_UNSPECIFIED","description":"- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)","enum":["VERIFICATION_ERROR_UNSPECIFIED","VERIFICATION_ERROR_INVALID_FORMAT","VERIFICATION_ERROR_EXPIRED","VERIFICATION_ERROR_REVOKED","VERIFICATION_ERROR_NOT_FOUND","VERIFICATION_ERROR_SIGNATURE_INVALID","VERIFICATION_ERROR_INTERNAL","VERIFICATION_ERROR_IP_NOT_ALLOWED","VERIFICATION_ERROR_RATE_LIMITED"],"title":"VerificationErrorCode provides type-safe error codes for verification failures","type":"string"},"error_message":{"title":"Human-readable error message (only set if is_active=false)","type":"string"},"expire_time":{"format":"date-time","type":"string"},"is_active":{"type":"boolean"},"issuer":{"description":"The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.","type":"string"},"key_id":{"type":"string"},"metadata":{"type":"object"},"rate_limit_policy":{"description":"RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.","properties":{"quota":{"description":"quota is the number of requests allowed per window.","format":"int64","type":"string"},"unit":{"title":"unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"","type":"string"},"window":{"description":"window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).","type":"string"}},"type":"object","title":"v2alpha1RateLimitPolicy"},"rate_limit_remaining":{"description":"Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).","format":"int64","type":"string"},"rate_limit_reset_time":{"description":"Time when the rate limiter returns to full capacity (all quota recovered).","format":"date-time","type":"string"},"scopes":{"items":{"type":"string"},"type":"array"},"visibility":{"default":"KEY_VISIBILITY_UNSPECIFIED","description":"KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET","enum":["KEY_VISIBILITY_UNSPECIFIED","KEY_VISIBILITY_SECRET","KEY_VISIBILITY_PUBLIC"],"type":"string","title":"v2alpha1KeyVisibility"}},"type":"object","title":"v2alpha1VerifyAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "actor_id": { "type": "string" },
+ "error_code": {
+ "default": "VERIFICATION_ERROR_UNSPECIFIED",
+ "description": "- VERIFICATION_ERROR_UNSPECIFIED: No error (key is valid)\n - VERIFICATION_ERROR_INVALID_FORMAT: Credential format is invalid\n - VERIFICATION_ERROR_EXPIRED: Credential has expired\n - VERIFICATION_ERROR_REVOKED: Credential has been revoked\n - VERIFICATION_ERROR_NOT_FOUND: Credential not found in database\n - VERIFICATION_ERROR_SIGNATURE_INVALID: Cryptographic signature verification failed\n - VERIFICATION_ERROR_INTERNAL: Internal server error during verification\n - VERIFICATION_ERROR_IP_NOT_ALLOWED: Request IP is not in the key's allowed CIDR ranges\n - VERIFICATION_ERROR_RATE_LIMITED: Rate limit quota exhausted (commercial-only)",
+ "enum": [
+ "VERIFICATION_ERROR_UNSPECIFIED",
+ "VERIFICATION_ERROR_INVALID_FORMAT",
+ "VERIFICATION_ERROR_EXPIRED",
+ "VERIFICATION_ERROR_REVOKED",
+ "VERIFICATION_ERROR_NOT_FOUND",
+ "VERIFICATION_ERROR_SIGNATURE_INVALID",
+ "VERIFICATION_ERROR_INTERNAL",
+ "VERIFICATION_ERROR_IP_NOT_ALLOWED",
+ "VERIFICATION_ERROR_RATE_LIMITED"
+ ],
+ "title": "VerificationErrorCode provides type-safe error codes for verification failures",
+ "type": "string"
+ },
+ "error_message": {
+ "title": "Human-readable error message (only set if is_active=false)",
+ "type": "string"
+ },
+ "expire_time": { "format": "date-time", "type": "string" },
+ "is_active": { "type": "boolean" },
+ "issuer": {
+ "description": "The configured token issuer for this project. For derived tokens (JWT/macaroon),\nthis matches the iss claim embedded in the verified token.",
+ "type": "string"
+ },
+ "key_id": { "type": "string" },
+ "metadata": { "type": "object" },
+ "rate_limit_policy": {
+ "description": "RateLimitPolicy describes the rate limit policy for an API key.\n\nIn OSS mode, this policy is informational and meant to be consumed by\nupstream gateways (Envoy, Cloudflare, etc.) for enforcement.\nIn commercial mode, Talos enforces rate limits using in-memory or Redis backends,\nboth powered by the GCRA (Generic Cell Rate Algorithm).\n\nCompliant with draft-ietf-httpapi-ratelimit-headers-10.",
+ "properties": {
+ "quota": {
+ "description": "quota is the number of requests allowed per window.",
+ "format": "int64",
+ "type": "string"
+ },
+ "unit": {
+ "title": "unit describes the quota unit type.\nDefault: \"requests\"\nOther valid values per IETF spec: \"content-bytes\", \"concurrent-requests\"",
+ "type": "string"
+ },
+ "window": {
+ "description": "window is the time window for the quota.\nCommon values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).",
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1RateLimitPolicy"
+ },
+ "rate_limit_remaining": {
+ "description": "Approximate number of requests available before the rate limit is reached\n(commercial-only, only set when enforcement is active).",
+ "format": "int64",
+ "type": "string"
+ },
+ "rate_limit_reset_time": {
+ "description": "Time when the rate limiter returns to full capacity (all quota recovered).",
+ "format": "date-time",
+ "type": "string"
+ },
+ "scopes": { "items": { "type": "string" }, "type": "array" },
+ "visibility": {
+ "default": "KEY_VISIBILITY_UNSPECIFIED",
+ "description": "KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys.\nPublic keys use a different configurable prefix for visual distinction.\nBoth types share the same scope/permission system — visibility is about exposure safety.\n\n - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET",
+ "enum": [
+ "KEY_VISIBILITY_UNSPECIFIED",
+ "KEY_VISIBILITY_SECRET",
+ "KEY_VISIBILITY_PUBLIC"
+ ],
+ "type": "string",
+ "title": "v2alpha1KeyVisibility"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1VerifyAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/admin-verify-api-key.api.mdx b/docs/talos/reference/api/admin-verify-api-key.api.mdx
index d832dc4c91..d40a372fe7 100644
--- a/docs/talos/reference/api/admin-verify-api-key.api.mdx
+++ b/docs/talos/reference/api/admin-verify-api-key.api.mdx
@@ -5,80 +5,41 @@ description: "Verifies a single API key or derived token. Validates the credenti
sidebar_label: "Verify API Key"
hide_title: true
hide_table_of_contents: true
-api: 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
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Verifies a single API key or derived token. Validates the credential's
-signature, expiration, and revocation status. Works with any credential
-type (issued keys, imported keys, JWT, macaroon). The verification result
-includes decoded claims and metadata — admin access only.
+Verifies a single API key or derived token. Validates the credential's signature, expiration, and revocation status. Works with
+any credential type (issued keys, imported keys, JWT, macaroon). The verification result includes decoded claims and metadata —
+admin access only.
Cache Control (HTTP Headers):
- - Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
- - Cache-Control: no-store - Bypasses cache read AND write (never cached)
- - Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
-```http
-POST /v2alpha1/admin/apiKeys:verify
-{
- "credential": "sk_live_abc123..."
-}
-```
+- Cache-Control: no-cache - Bypasses cache read, forces fresh DB lookup
+- Cache-Control: no-store - Bypasses cache read AND write (never cached)
+- Pragma: no-cache - Same as Cache-Control: no-cache (HTTP/1.0)
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/ory-talos-api.info.mdx b/docs/talos/reference/api/ory-talos-api.info.mdx
index dadc4eb06f..8d75faadb4 100644
--- a/docs/talos/reference/api/ory-talos-api.info.mdx
+++ b/docs/talos/reference/api/ory-talos-api.info.mdx
@@ -1,42 +1,32 @@
---
id: ory-talos-api
title: "Ory Talos API"
-description: "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
+description:
+ "Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
+ verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access."
sidebar_label: "Ory Talos API"
hide_title: true
custom_edit_url: null
---
-import ApiLogo from "@theme/ApiLogo";
-import Heading from "@theme/Heading";
-import SchemaTabs from "@theme/SchemaTabs";
-import TabItem from "@theme/TabItem";
-import Export from "@theme/ApiExplorer/Export";
+import ApiLogo from "@theme/ApiLogo"
+import Heading from "@theme/Heading"
+import SchemaTabs from "@theme/SchemaTabs"
+import TabItem from "@theme/TabItem"
+import Export from "@theme/ApiExplorer/Export"
-
-
+
-
-
+
-
-
-Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys, verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
+Ory Talos is a high-performance static credential management service. It handles the full credential lifecycle: issuing keys,
+verifying them at low latency, deriving short-lived tokens (JWT and Macaroon), and revoking access.
The API is split into two services:
- **StaticCredentials** — admin operations: key lifecycle (issue, rotate, revoke, import, derive tokens, JWKS) and verification
- **SelfService** — self-service revocation for credential holders
-
-
### Quick Links
- [**Admin Plane**](./admin-issue-api-key) — Key lifecycle management (issue, rotate, revoke, import, derive tokens, JWKS)
diff --git a/docs/talos/reference/api/revoke-api-key.RequestSchema.json b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
index 7d776c606e..6f51da83ec 100644
--- a/docs/talos/reference/api/revoke-api-key.RequestSchema.json
+++ b/docs/talos/reference/api/revoke-api-key.RequestSchema.json
@@ -1 +1,36 @@
-{"title":"Body","body":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","properties":{"credential":{"title":"Full API key secret or imported key (REQUIRED)","type":"string"},"reason":{"default":"REVOCATION_REASON_UNSPECIFIED","description":"RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation","enum":["REVOCATION_REASON_UNSPECIFIED","REVOCATION_REASON_KEY_COMPROMISE","REVOCATION_REASON_AFFILIATION_CHANGED","REVOCATION_REASON_SUPERSEDED","REVOCATION_REASON_PRIVILEGE_WITHDRAWN"],"type":"string","title":"v2alpha1RevocationReason"}},"type":"object","title":"v2alpha1SelfRevokeAPIKeyRequest"}}},"description":"SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.","required":true,"x-originalParamName":"body"}}
\ No newline at end of file
+{
+ "title": "Body",
+ "body": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "properties": {
+ "credential": {
+ "title": "Full API key secret or imported key (REQUIRED)",
+ "type": "string"
+ },
+ "reason": {
+ "default": "REVOCATION_REASON_UNSPECIFIED",
+ "description": "RevocationReason provides structured revocation reasons inspired by RFC 5280.\nUsed in both admin and self-revocation flows.\n\n - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only: not allowed in self-revocation",
+ "enum": [
+ "REVOCATION_REASON_UNSPECIFIED",
+ "REVOCATION_REASON_KEY_COMPROMISE",
+ "REVOCATION_REASON_AFFILIATION_CHANGED",
+ "REVOCATION_REASON_SUPERSEDED",
+ "REVOCATION_REASON_PRIVILEGE_WITHDRAWN"
+ ],
+ "type": "string",
+ "title": "v2alpha1RevocationReason"
+ }
+ },
+ "type": "object",
+ "title": "v2alpha1SelfRevokeAPIKeyRequest"
+ }
+ }
+ },
+ "description": "SelfRevokeAPIKeyRequest allows an API key holder to revoke their own key\nby providing the full key secret as proof of possession.",
+ "required": true,
+ "x-originalParamName": "body"
+ }
+}
diff --git a/docs/talos/reference/api/revoke-api-key.StatusCodes.json b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
index b870249cb8..72c1ff7d8f 100644
--- a/docs/talos/reference/api/revoke-api-key.StatusCodes.json
+++ b/docs/talos/reference/api/revoke-api-key.StatusCodes.json
@@ -1 +1,40 @@
-{"responses":{"200":{"content":{"application/json":{"schema":{"description":"SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success","type":"object","title":"v2alpha1SelfRevokeAPIKeyResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object","title":"protobufAny"},"type":"array"},"message":{"type":"string"}},"type":"object","title":"rpcStatus"}}},"description":"An unexpected error response."}}}
\ No newline at end of file
+{
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "description": "SelfRevokeAPIKeyResponse is returned on successful self-revocation.\n\nEmpty on success",
+ "type": "object",
+ "title": "v2alpha1SelfRevokeAPIKeyResponse"
+ }
+ }
+ },
+ "description": "A successful response."
+ },
+ "default": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "properties": {
+ "code": { "format": "int32", "type": "integer" },
+ "details": {
+ "items": {
+ "additionalProperties": {},
+ "properties": { "@type": { "type": "string" } },
+ "type": "object",
+ "title": "protobufAny"
+ },
+ "type": "array"
+ },
+ "message": { "type": "string" }
+ },
+ "type": "object",
+ "title": "rpcStatus"
+ }
+ }
+ },
+ "description": "An unexpected error response."
+ }
+ }
+}
diff --git a/docs/talos/reference/api/revoke-api-key.api.mdx b/docs/talos/reference/api/revoke-api-key.api.mdx
index 742ea686ea..f40f8fd9a9 100644
--- a/docs/talos/reference/api/revoke-api-key.api.mdx
+++ b/docs/talos/reference/api/revoke-api-key.api.mdx
@@ -5,79 +5,36 @@ description: "Allows an API key holder to revoke their own key. The caller must
sidebar_label: "Revoke API Key"
hide_title: true
hide_table_of_contents: true
-api: eJztV21v2zYQ/iuH+5QEstOmGDDo07zEadW0iWsnDYYoSGnpbLGhSJWknAiGgf2I/cL9koGk/BLXbdBhH4Zh+RKJujvey3PPneeYk8k0ryxXEmPsCaEeDDAJvUEC99RAoUROGqwCTTN1T2AL4hrUg3Sfu3BZEGRMCNJQ1sZCpdWM55RKWxBMaiFWlgxlmiww42TUBNQEKmUMGcOV7MKoriqlrQFuTE35Us2kkskceOk+Uu6PuvD2+hLccckyppWSYNU9SQMZk1JZGBMYEpNOcDmHPVtQk0qmCYxllgQZs99NZSqd+4Nh8jF513/dv7tOLt+cDHvX56CJGSWBG3D2mEsL5TBRem04Yy5pqdxjecllR0nRBJufPn0qrK1SObgYXcLh7IiJqmAvD1nFz6gxsbMw9J6lcp5KgBQzTTlJy5lIMYYUzf2d4DO6Y+Ps5dGrbrebYhQkg2NBatj/eHHcu0wuzu+G/d7o4vzurP/b3fHF+8Hw4n0y6qeYyoX3ByNUFWnvcZJjjOH+3iA5owYj1PSlJmN/VXmD8RwzJS1J6x5ZVQkeQj38bBxI5miygkrmnp6iZ7QKLBgeBqshfT+AqlSOmxZIXE5hhaTnUYQRVtpFajkZH8kqse7NcisIYzzdgUuln4AM9ob9D1fJsH+yjxHapnJ6xmoup7iI2jKEFExYLazL6VfluDofDfrHyWnSP8FoK1nDFYSGAWtt5xgwVteZrTXlsMZZi0gDXJqKu2/jBoanx/DT0c8vuqm8MpQDlzBWtgCPSN8gW2iFiauERyl04GuHd7RCDL0VvuMn3cDltnmMkGRdYnzzbDKew+5Okd7pafIuCUfHb3rnr79hanQ16A9H/ZNvfN4RJd5uFzlaoWXZwNsVw8VipaTGnymzO5S+0RO4cMr/wvZxTODghbHVNUX42FGaT7lkYsA0K89Z6aIbO6LwbWAqJU3otaMXL/5R8gimHQdrsrWWlIOSYOosI2MmtdhGn4d1v6xssyGHf6dE4eZdNept3r+MvoteruWBH8jAFlepnNz/idIlc4TCpX11tA6AS0tT0uEyy7jwWtxS6R9YnnN3DxODTbOLbUr8JZibb5Pad8BcaWXVuJ70pK96K8a0Zv69JGPY9Adt6iobWWZrszPNEmpJjxVljo5Ja6U3s+3MsqlxPOOKNyI94xm5Hi7JFsoNuEoZd1vFbIExfm8IY4SuMsP1COw/srIStD0/1sywZP9nWG4RIZcT9TXWL3QDl0wot+wAg4JPi05F2hdeZmFJ4RmsL4eSSTalkqQFE6LtQmKhYDIXZNY9vqEi+ISyJhMU+5XKUYFbniKYkeaTpqWGEpgFoR5AMEsyayLISfOZ+2oKpW3H7SH5cr/aWy5e79vFaz/yr56GnA7zzbFarRxhcQOmEtwCl1aBfVDLCEzsxDpwcDDy8R6vfDcHB/Dn73+0c2y1uZjYc9gqMNjzu2IEWrmtLmrZMGoHeRsKtc5H8Pb6bLTv/fUp4MsNzruwxlF7uWeX1tXNQeyWwI00By42G8heV7c3SDDCGWkT6r5EoUOGA2jJPCHIQKoBjj5nYSt7ApoNWvl/Tf/vruktXVp6tIeVYFw6rNTar6+BzG7WMIpwB53dRlg48otvcD4fM0NXWiwW7vhLTbrB+OY2whnTnI0dXG9uFxEWxHLSGN/M8Z4ajPE4YK1z6dxx4qL2lL89zhbRUqOXZVTZ78pu8rNLOkZhkYjnWPrZh5o9OHplDxij/83i294J+LM5CiantZ81GGy6v78ArPkkpA==
+api: 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
sidebar_class_name: "post api-method"
info_path: reference/api/ory-talos-api
custom_edit_url: null
---
-import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
-import ParamsDetails from "@theme/ParamsDetails";
-import RequestSchema from "@theme/RequestSchema";
-import StatusCodes from "@theme/StatusCodes";
-import OperationTabs from "@theme/OperationTabs";
-import TabItem from "@theme/TabItem";
-import Heading from "@theme/Heading";
-import Translate from "@docusaurus/Translate";
-
-
-
-
-
-
-
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"
+import ParamsDetails from "@theme/ParamsDetails"
+import RequestSchema from "@theme/RequestSchema"
+import StatusCodes from "@theme/StatusCodes"
+import OperationTabs from "@theme/OperationTabs"
+import TabItem from "@theme/TabItem"
+import Heading from "@theme/Heading"
+import Translate from "@docusaurus/Translate"
+
+
-Allows an API key holder to revoke their own key. The caller must provide
-the full API key secret as proof of possession. Supports issued API keys
-and imported keys. JWT and macaroon tokens cannot be self-revoked (they
-are stateless).
+Allows an API key holder to revoke their own key. The caller must provide the full API key secret as proof of possession. Supports
+issued API keys and imported keys. JWT and macaroon tokens cannot be self-revoked (they are stateless).
-The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation
-(admin-only).
+The PRIVILEGE_WITHDRAWN reason is not allowed for self-revocation (admin-only).
-```http
-POST /v2alpha1/apiKeys:selfRevoke
-{
- "credential": "sk_live_abc123...",
- "reason": "REVOCATION_REASON_KEY_COMPROMISE"
-}
-```
-
-
+
Request
-
-
-
-
-
-
-
-
-
-
-
+
+
-
\ No newline at end of file
+
diff --git a/docs/talos/reference/api/sidebar.ts b/docs/talos/reference/api/sidebar.ts
index 9551b2780c..e688743952 100644
--- a/docs/talos/reference/api/sidebar.ts
+++ b/docs/talos/reference/api/sidebar.ts
@@ -1,4 +1,4 @@
-import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"
const sidebar: SidebarsConfig = {
apisidebar: [
@@ -121,6 +121,6 @@ const sidebar: SidebarsConfig = {
],
},
],
-};
+}
-export default sidebar.apisidebar;
+export default sidebar.apisidebar
diff --git a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
index a7c1557d43..22a85fd248 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-ecdsa.md
@@ -9,15 +9,15 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk generate ecdsa
Generate an ECDSA key pair
### Synopsis
-Generate an ECDSA key pair using the specified elliptic curve.
-Key size is determined by the curve: P-256 (256-bit), P-384 (384-bit), P-521 (521-bit).
-Default curve: P-256.
+Generate an ECDSA key pair using the specified elliptic curve. Key size is determined by the curve: P-256 (256-bit), P-384
+(384-bit), P-521 (521-bit). Default curve: P-256.
```
talos jwk generate ecdsa [flags]
@@ -57,5 +57,4 @@ talos jwk generate ecdsa [flags]
### See also
-* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
-
+- [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-eddsa.md b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
index 12bc60a75f..a5833a3c5b 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-eddsa.md
@@ -9,14 +9,14 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk generate eddsa
Generate an EdDSA (Ed25519) key pair
### Synopsis
-Generate an EdDSA key pair using the Ed25519 curve.
-Ed25519 uses a fixed 256-bit key size.
+Generate an EdDSA key pair using the Ed25519 curve. Ed25519 uses a fixed 256-bit key size.
```
talos jwk generate eddsa [flags]
@@ -58,5 +58,4 @@ talos jwk generate eddsa [flags]
### See also
-* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
-
+- [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-hmac.md b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
index 660a65d016..edfe70d2ad 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-hmac.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-hmac.md
@@ -9,15 +9,15 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk generate hmac
Generate an HMAC secret key
### Synopsis
-Generate a symmetric HMAC secret key.
-Default size is 512 bits. Minimum is 256 bits.
-Algorithm is determined by key size: 256→HS256, 384→HS384, ≥512→HS512.
+Generate a symmetric HMAC secret key. Default size is 512 bits. Minimum is 256 bits. Algorithm is determined by key size:
+256→HS256, 384→HS384, ≥512→HS512.
```
talos jwk generate hmac [flags]
@@ -56,5 +56,4 @@ talos jwk generate hmac [flags]
### See also
-* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
-
+- [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate-rsa.md b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
index 18685d9ee5..f39c2c9636 100644
--- a/docs/talos/reference/cli/talos-jwk-generate-rsa.md
+++ b/docs/talos/reference/cli/talos-jwk-generate-rsa.md
@@ -9,14 +9,14 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk generate rsa
Generate an RSA key pair
### Synopsis
-Generate an RSA key pair with the specified key size.
-Default is 2048 bits. Minimum is 2048 bits.
+Generate an RSA key pair with the specified key size. Default is 2048 bits. Minimum is 2048 bits.
```
talos jwk generate rsa [flags]
@@ -60,5 +60,4 @@ talos jwk generate rsa [flags]
### See also
-* [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
-
+- [talos jwk generate](talos-jwk-generate.md) Generate a new JWK key
diff --git a/docs/talos/reference/cli/talos-jwk-generate.md b/docs/talos/reference/cli/talos-jwk-generate.md
index c6ebfa524c..111309f8b1 100644
--- a/docs/talos/reference/cli/talos-jwk-generate.md
+++ b/docs/talos/reference/cli/talos-jwk-generate.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk generate
Generate a new JWK key
@@ -32,9 +33,8 @@ Generate a new cryptographic key in JWK format for signing or encryption.
### See also
-* [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
-* [talos jwk generate ecdsa](talos-jwk-generate-ecdsa.md) - Generate an ECDSA key pair
-* [talos jwk generate eddsa](talos-jwk-generate-eddsa.md) - Generate an EdDSA (Ed25519) key pair
-* [talos jwk generate hmac](talos-jwk-generate-hmac.md) - Generate an HMAC secret key
-* [talos jwk generate rsa](talos-jwk-generate-rsa.md) - Generate an RSA key pair
-
+- [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
+- [talos jwk generate ecdsa](talos-jwk-generate-ecdsa.md) - Generate an ECDSA key pair
+- [talos jwk generate eddsa](talos-jwk-generate-eddsa.md) - Generate an EdDSA (Ed25519) key pair
+- [talos jwk generate hmac](talos-jwk-generate-hmac.md) - Generate an HMAC secret key
+- [talos jwk generate rsa](talos-jwk-generate-rsa.md) - Generate an RSA key pair
diff --git a/docs/talos/reference/cli/talos-jwk-get.md b/docs/talos/reference/cli/talos-jwk-get.md
index 49576b158c..0594c8ec6d 100644
--- a/docs/talos/reference/cli/talos-jwk-get.md
+++ b/docs/talos/reference/cli/talos-jwk-get.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk get
Fetch the server's JSON Web Key Set (JWKS)
@@ -17,12 +18,11 @@ Fetch the server's JSON Web Key Set (JWKS)
Fetch the public signing keys used to verify derived JWT tokens.
-The JWKS is served at GET /v2alpha1/admin/derivedKeys/jwks.json and includes the active
-signing key plus any retired keys still inside the verification window.
+The JWKS is served at GET /v2alpha1/admin/derivedKeys/jwks.json and includes the active signing key plus any retired keys still
+inside the verification window.
-Clients verifying derived tokens should cache the response for 5 to 15 minutes and
-refetch when they encounter a token with an unknown 'kid'. Polling more aggressively does
-not shorten the practical revocation window — that window is bounded by the longest
+Clients verifying derived tokens should cache the response for 5 to 15 minutes and refetch when they encounter a token with an
+unknown 'kid'. Polling more aggressively does not shorten the practical revocation window — that window is bounded by the longest
issued token TTL, not by the JWKS cache.
```
@@ -51,5 +51,4 @@ talos jwk get [flags]
### See also
-* [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
-
+- [talos jwk](talos-jwk.md) Generate JSON Web Keys (JWK/JWKS)
diff --git a/docs/talos/reference/cli/talos-jwk.md b/docs/talos/reference/cli/talos-jwk.md
index 4bd1673a2a..8d2741ead6 100644
--- a/docs/talos/reference/cli/talos-jwk.md
+++ b/docs/talos/reference/cli/talos-jwk.md
@@ -9,14 +9,15 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos jwk
Generate JSON Web Keys (JWK/JWKS)
### Synopsis
-Generate cryptographic keys in JSON Web Key (JWK) format.
-Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC algorithms.
+Generate cryptographic keys in JSON Web Key (JWK) format. Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC
+algorithms.
### Options
@@ -33,7 +34,6 @@ Supports EdDSA (Ed25519), ECDSA (P-256, P-384, P-521), RSA, and HMAC algorithms.
### See also
-* [talos](talos.md) Multi-tenant API key management service
-* [talos jwk generate](talos-jwk-generate.md) - Generate a new JWK key
-* [talos jwk get](talos-jwk-get.md) - Fetch the server's JSON Web Key Set (JWKS)
-
+- [talos](talos.md) Multi-tenant API key management service
+- [talos jwk generate](talos-jwk-generate.md) - Generate a new JWK key
+- [talos jwk get](talos-jwk-get.md) - Fetch the server's JSON Web Key Set (JWKS)
diff --git a/docs/talos/reference/cli/talos-keys-batch-verify.md b/docs/talos/reference/cli/talos-keys-batch-verify.md
index 33ad2aa115..057472c09a 100644
--- a/docs/talos/reference/cli/talos-keys-batch-verify.md
+++ b/docs/talos/reference/cli/talos-keys-batch-verify.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys batch-verify
Verify multiple credentials in a single request
@@ -35,5 +36,4 @@ talos keys batch-verify [credentials...] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-derive-token.md b/docs/talos/reference/cli/talos-keys-derive-token.md
index aac5bf037b..9d9190eb09 100644
--- a/docs/talos/reference/cli/talos-keys-derive-token.md
+++ b/docs/talos/reference/cli/talos-keys-derive-token.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys derive-token
Derive a short-lived JWT or macaroon from an existing API key
@@ -41,5 +42,4 @@ talos keys derive-token [api-key-token] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-batch-import.md b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
index 186c348431..5c0af749d7 100644
--- a/docs/talos/reference/cli/talos-keys-imported-batch-import.md
+++ b/docs/talos/reference/cli/talos-keys-imported-batch-import.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported batch-import
Batch import API keys from a JSON file
@@ -39,5 +40,4 @@ talos keys imported batch-import --file keys.json [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-delete.md b/docs/talos/reference/cli/talos-keys-imported-delete.md
index dce11140ff..6d9c3f22e1 100644
--- a/docs/talos/reference/cli/talos-keys-imported-delete.md
+++ b/docs/talos/reference/cli/talos-keys-imported-delete.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported delete
Permanently delete an imported API key
@@ -34,5 +35,4 @@ talos keys imported delete [key-id] [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-get.md b/docs/talos/reference/cli/talos-keys-imported-get.md
index 812438b755..cf66b03669 100644
--- a/docs/talos/reference/cli/talos-keys-imported-get.md
+++ b/docs/talos/reference/cli/talos-keys-imported-get.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported get
Get details of an imported API key
@@ -34,5 +35,4 @@ talos keys imported get [key-id] [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-import.md b/docs/talos/reference/cli/talos-keys-imported-import.md
index 49053abb84..96795e4f1e 100644
--- a/docs/talos/reference/cli/talos-keys-imported-import.md
+++ b/docs/talos/reference/cli/talos-keys-imported-import.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported import
Import an external API key
@@ -42,5 +43,4 @@ talos keys imported import [name] [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-list.md b/docs/talos/reference/cli/talos-keys-imported-list.md
index 49fcca7548..bf1a42fb01 100644
--- a/docs/talos/reference/cli/talos-keys-imported-list.md
+++ b/docs/talos/reference/cli/talos-keys-imported-list.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported list
List imported API keys
@@ -38,5 +39,4 @@ talos keys imported list [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported-revoke.md b/docs/talos/reference/cli/talos-keys-imported-revoke.md
index cd4cce9d4f..aa287cdaf1 100644
--- a/docs/talos/reference/cli/talos-keys-imported-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-imported-revoke.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported revoke
Revoke an imported API key
@@ -36,5 +37,4 @@ talos keys imported revoke [key-id] [flags]
### See also
-* [talos keys imported](talos-keys-imported.md) Manage imported API keys
-
+- [talos keys imported](talos-keys-imported.md) Manage imported API keys
diff --git a/docs/talos/reference/cli/talos-keys-imported.md b/docs/talos/reference/cli/talos-keys-imported.md
index 68368497b1..274a5b8646 100644
--- a/docs/talos/reference/cli/talos-keys-imported.md
+++ b/docs/talos/reference/cli/talos-keys-imported.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys imported
Manage imported API keys
@@ -34,11 +35,10 @@ Import, list, get, revoke, and delete externally-created API keys.
### See also
-* [talos keys](talos-keys.md) Manage API keys
-* [talos keys imported batch-import](talos-keys-imported-batch-import.md) - Batch import API keys from a JSON file
-* [talos keys imported delete](talos-keys-imported-delete.md) - Permanently delete an imported API key
-* [talos keys imported get](talos-keys-imported-get.md) - Get details of an imported API key
-* [talos keys imported import](talos-keys-imported-import.md) - Import an external API key
-* [talos keys imported list](talos-keys-imported-list.md) - List imported API keys
-* [talos keys imported revoke](talos-keys-imported-revoke.md) - Revoke an imported API key
-
+- [talos keys](talos-keys.md) Manage API keys
+- [talos keys imported batch-import](talos-keys-imported-batch-import.md) - Batch import API keys from a JSON file
+- [talos keys imported delete](talos-keys-imported-delete.md) - Permanently delete an imported API key
+- [talos keys imported get](talos-keys-imported-get.md) - Get details of an imported API key
+- [talos keys imported import](talos-keys-imported-import.md) - Import an external API key
+- [talos keys imported list](talos-keys-imported-list.md) - List imported API keys
+- [talos keys imported revoke](talos-keys-imported-revoke.md) - Revoke an imported API key
diff --git a/docs/talos/reference/cli/talos-keys-issue.md b/docs/talos/reference/cli/talos-keys-issue.md
index 9975657106..b2ad52f081 100644
--- a/docs/talos/reference/cli/talos-keys-issue.md
+++ b/docs/talos/reference/cli/talos-keys-issue.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issue
Issue a new API key
@@ -41,5 +42,4 @@ talos keys issue [name] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-get.md b/docs/talos/reference/cli/talos-keys-issued-get.md
index 607691f73e..dcd11f3d67 100644
--- a/docs/talos/reference/cli/talos-keys-issued-get.md
+++ b/docs/talos/reference/cli/talos-keys-issued-get.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued get
Get details of an issued API key
@@ -34,5 +35,4 @@ talos keys issued get [key-id] [flags]
### See also
-* [talos keys issued](talos-keys-issued.md) Manage issued API keys
-
+- [talos keys issued](talos-keys-issued.md) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-issue.md b/docs/talos/reference/cli/talos-keys-issued-issue.md
index 80191ebd5f..adb2a91d87 100644
--- a/docs/talos/reference/cli/talos-keys-issued-issue.md
+++ b/docs/talos/reference/cli/talos-keys-issued-issue.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued issue
Issue a new API key
@@ -41,5 +42,4 @@ talos keys issued issue [name] [flags]
### See also
-* [talos keys issued](talos-keys-issued.md) Manage issued API keys
-
+- [talos keys issued](talos-keys-issued.md) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-list.md b/docs/talos/reference/cli/talos-keys-issued-list.md
index 2c1904420e..5a42b0b869 100644
--- a/docs/talos/reference/cli/talos-keys-issued-list.md
+++ b/docs/talos/reference/cli/talos-keys-issued-list.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued list
List issued API keys
@@ -38,5 +39,4 @@ talos keys issued list [flags]
### See also
-* [talos keys issued](talos-keys-issued.md) Manage issued API keys
-
+- [talos keys issued](talos-keys-issued.md) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-rotate.md b/docs/talos/reference/cli/talos-keys-issued-rotate.md
index 1bd5645ba2..cf4b20c11b 100644
--- a/docs/talos/reference/cli/talos-keys-issued-rotate.md
+++ b/docs/talos/reference/cli/talos-keys-issued-rotate.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued rotate
Rotate an issued API key (revokes old key, creates new one)
@@ -37,5 +38,4 @@ talos keys issued rotate [key-id] [flags]
### See also
-* [talos keys issued](talos-keys-issued.md) Manage issued API keys
-
+- [talos keys issued](talos-keys-issued.md) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued-update.md b/docs/talos/reference/cli/talos-keys-issued-update.md
index deebf0fb86..88f1cde2ca 100644
--- a/docs/talos/reference/cli/talos-keys-issued-update.md
+++ b/docs/talos/reference/cli/talos-keys-issued-update.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued update
Update an issued API key
@@ -40,5 +41,4 @@ talos keys issued update [key-id] [flags]
### See also
-* [talos keys issued](talos-keys-issued.md) Manage issued API keys
-
+- [talos keys issued](talos-keys-issued.md) Manage issued API keys
diff --git a/docs/talos/reference/cli/talos-keys-issued.md b/docs/talos/reference/cli/talos-keys-issued.md
index 223ed0c57d..2e9ea3ccc9 100644
--- a/docs/talos/reference/cli/talos-keys-issued.md
+++ b/docs/talos/reference/cli/talos-keys-issued.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys issued
Manage issued API keys
@@ -34,10 +35,9 @@ Get, list, update, and rotate issued API keys.
### See also
-* [talos keys](talos-keys.md) Manage API keys
-* [talos keys issued get](talos-keys-issued-get.md) - Get details of an issued API key
-* [talos keys issued issue](talos-keys-issued-issue.md) - Issue a new API key
-* [talos keys issued list](talos-keys-issued-list.md) - List issued API keys
-* [talos keys issued rotate](talos-keys-issued-rotate.md) - Rotate an issued API key (revokes old key, creates new one)
-* [talos keys issued update](talos-keys-issued-update.md) - Update an issued API key
-
+- [talos keys](talos-keys.md) Manage API keys
+- [talos keys issued get](talos-keys-issued-get.md) - Get details of an issued API key
+- [talos keys issued issue](talos-keys-issued-issue.md) - Issue a new API key
+- [talos keys issued list](talos-keys-issued-list.md) - List issued API keys
+- [talos keys issued rotate](talos-keys-issued-rotate.md) - Rotate an issued API key (revokes old key, creates new one)
+- [talos keys issued update](talos-keys-issued-update.md) - Update an issued API key
diff --git a/docs/talos/reference/cli/talos-keys-revoke.md b/docs/talos/reference/cli/talos-keys-revoke.md
index 18ee6a8392..e06478e939 100644
--- a/docs/talos/reference/cli/talos-keys-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-revoke.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys revoke
Revoke an API key
@@ -35,5 +36,4 @@ talos keys revoke [key-id] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-self-revoke.md b/docs/talos/reference/cli/talos-keys-self-revoke.md
index f453166adb..f83e056443 100644
--- a/docs/talos/reference/cli/talos-keys-self-revoke.md
+++ b/docs/talos/reference/cli/talos-keys-self-revoke.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys self-revoke
Revoke an API key using the credential itself as proof
@@ -39,5 +40,4 @@ talos keys self-revoke [credential] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys-verify.md b/docs/talos/reference/cli/talos-keys-verify.md
index 9f9edbe1d1..d08d1450a1 100644
--- a/docs/talos/reference/cli/talos-keys-verify.md
+++ b/docs/talos/reference/cli/talos-keys-verify.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys verify
Verify a credential (API key or token)
@@ -39,5 +40,4 @@ talos keys verify [credential] [flags]
### See also
-* [talos keys](talos-keys.md) Manage API keys
-
+- [talos keys](talos-keys.md) Manage API keys
diff --git a/docs/talos/reference/cli/talos-keys.md b/docs/talos/reference/cli/talos-keys.md
index 4798a62425..41e99e052f 100644
--- a/docs/talos/reference/cli/talos-keys.md
+++ b/docs/talos/reference/cli/talos-keys.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos keys
Manage API keys
@@ -34,13 +35,12 @@ Create, list, get, revoke, and rotate API keys.
### See also
-* [talos](talos.md) Multi-tenant API key management service
-* [talos keys batch-verify](talos-keys-batch-verify.md) - Verify multiple credentials in a single request
-* [talos keys derive-token](talos-keys-derive-token.md) - Derive a short-lived JWT or macaroon from an existing API key
-* [talos keys imported](talos-keys-imported.md) - Manage imported API keys
-* [talos keys issue](talos-keys-issue.md) - Issue a new API key
-* [talos keys issued](talos-keys-issued.md) - Manage issued API keys
-* [talos keys revoke](talos-keys-revoke.md) - Revoke an API key
-* [talos keys self-revoke](talos-keys-self-revoke.md) - Revoke an API key using the credential itself as proof
-* [talos keys verify](talos-keys-verify.md) - Verify a credential (API key or token)
-
+- [talos](talos.md) Multi-tenant API key management service
+- [talos keys batch-verify](talos-keys-batch-verify.md) - Verify multiple credentials in a single request
+- [talos keys derive-token](talos-keys-derive-token.md) - Derive a short-lived JWT or macaroon from an existing API key
+- [talos keys imported](talos-keys-imported.md) - Manage imported API keys
+- [talos keys issue](talos-keys-issue.md) - Issue a new API key
+- [talos keys issued](talos-keys-issued.md) - Manage issued API keys
+- [talos keys revoke](talos-keys-revoke.md) - Revoke an API key
+- [talos keys self-revoke](talos-keys-self-revoke.md) - Revoke an API key using the credential itself as proof
+- [talos keys verify](talos-keys-verify.md) - Verify a credential (API key or token)
diff --git a/docs/talos/reference/cli/talos-migrate-down.md b/docs/talos/reference/cli/talos-migrate-down.md
index 8a15ec3802..ca0205740e 100644
--- a/docs/talos/reference/cli/talos-migrate-down.md
+++ b/docs/talos/reference/cli/talos-migrate-down.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos migrate down
Rollback migrations
@@ -17,8 +18,7 @@ Rollback migrations
Roll back the last N migrations (default: 1).
-This is useful for reverting recent migrations in development.
-In production, use this carefully and ensure you have backups.
+This is useful for reverting recent migrations in development. In production, use this carefully and ensure you have backups.
```
talos migrate down [flags]
@@ -51,5 +51,4 @@ talos migrate down [flags]
### See also
-* [talos migrate](talos-migrate.md) Database migration tools
-
+- [talos migrate](talos-migrate.md) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-force.md b/docs/talos/reference/cli/talos-migrate-force.md
index df5775f5b3..df67f5292b 100644
--- a/docs/talos/reference/cli/talos-migrate-force.md
+++ b/docs/talos/reference/cli/talos-migrate-force.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos migrate force
Force set migration version (use with caution)
@@ -18,12 +19,12 @@ Force set migration version (use with caution)
Force the migration version to a specific value.
This is useful when:
- - A migration failed and left the database in a dirty state
- - You need to manually fix the database state
- - You want to mark a migration as applied without running it
-WARNING: This command should be used carefully as it can lead to
-inconsistent database state if used incorrectly.
+- A migration failed and left the database in a dirty state
+- You need to manually fix the database state
+- You want to mark a migration as applied without running it
+
+WARNING: This command should be used carefully as it can lead to inconsistent database state if used incorrectly.
```
talos migrate force VERSION [flags]
@@ -52,5 +53,4 @@ talos migrate force VERSION [flags]
### See also
-* [talos migrate](talos-migrate.md) Database migration tools
-
+- [talos migrate](talos-migrate.md) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-status.md b/docs/talos/reference/cli/talos-migrate-status.md
index 7d58414536..1c550f44e5 100644
--- a/docs/talos/reference/cli/talos-migrate-status.md
+++ b/docs/talos/reference/cli/talos-migrate-status.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos migrate status
Show migration status
@@ -18,9 +19,10 @@ Show migration status
Display the current database migration status.
Shows:
- - Current migration version
- - Whether the database is in a dirty state
- - Database connection info
+
+- Current migration version
+- Whether the database is in a dirty state
+- Database connection info
```
talos migrate status [flags]
@@ -42,5 +44,4 @@ talos migrate status [flags]
### See also
-* [talos migrate](talos-migrate.md) Database migration tools
-
+- [talos migrate](talos-migrate.md) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate-up.md b/docs/talos/reference/cli/talos-migrate-up.md
index 9c1cf6966d..346dceaeef 100644
--- a/docs/talos/reference/cli/talos-migrate-up.md
+++ b/docs/talos/reference/cli/talos-migrate-up.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos migrate up
Run all pending migrations
@@ -18,8 +19,9 @@ Run all pending migrations
Apply all pending migrations to the database.
The database connection string can be provided via:
- - DB_DSN environment variable
- - --database flag (overrides DB_DSN)
+
+- DB_DSN environment variable
+- --database flag (overrides DB_DSN)
```
talos migrate up [flags]
@@ -58,5 +60,4 @@ talos migrate up [flags]
### See also
-* [talos migrate](talos-migrate.md) Database migration tools
-
+- [talos migrate](talos-migrate.md) Database migration tools
diff --git a/docs/talos/reference/cli/talos-migrate.md b/docs/talos/reference/cli/talos-migrate.md
index 0d26134f47..4a580a2cb1 100644
--- a/docs/talos/reference/cli/talos-migrate.md
+++ b/docs/talos/reference/cli/talos-migrate.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos migrate
Database migration tools
@@ -32,9 +33,8 @@ Run database migrations for the API Key service
### See also
-* [talos](talos.md) Multi-tenant API key management service
-* [talos migrate down](talos-migrate-down.md) - Rollback migrations
-* [talos migrate force](talos-migrate-force.md) - Force set migration version (use with caution)
-* [talos migrate status](talos-migrate-status.md) - Show migration status
-* [talos migrate up](talos-migrate-up.md) - Run all pending migrations
-
+- [talos](talos.md) Multi-tenant API key management service
+- [talos migrate down](talos-migrate-down.md) - Rollback migrations
+- [talos migrate force](talos-migrate-force.md) - Force set migration version (use with caution)
+- [talos migrate status](talos-migrate-status.md) - Show migration status
+- [talos migrate up](talos-migrate-up.md) - Run all pending migrations
diff --git a/docs/talos/reference/cli/talos-proxy.md b/docs/talos/reference/cli/talos-proxy.md
index 75e87cd681..73dc1fa994 100644
--- a/docs/talos/reference/cli/talos-proxy.md
+++ b/docs/talos/reference/cli/talos-proxy.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos proxy
Start the edge proxy for caching verification requests
@@ -17,14 +18,12 @@ Start the edge proxy for caching verification requests
Start an edge proxy that caches verification responses from an upstream Talos server.
-The proxy caches successful verification responses to reduce latency and load on the upstream server.
-Only active (valid) verification responses are cached.
+The proxy caches successful verification responses to reduce latency and load on the upstream server. Only active (valid)
+verification responses are cached.
Cache bypass: Clients can bypass the cache by sending Cache-Control: no-cache header.
-The proxy exposes health endpoints:
- /health/alive - Always returns 200 OK
- /health/ready - Returns 200 OK if upstream is reachable
+The proxy exposes health endpoints: /health/alive - Always returns 200 OK /health/ready - Returns 200 OK if upstream is reachable
```
talos proxy [flags]
@@ -60,5 +59,4 @@ talos proxy [flags]
### See also
-* [talos](talos.md) Multi-tenant API key management service
-
+- [talos](talos.md) Multi-tenant API key management service
diff --git a/docs/talos/reference/cli/talos-serve-admin.md b/docs/talos/reference/cli/talos-serve-admin.md
index dea6b38d04..fdecf39225 100644
--- a/docs/talos/reference/cli/talos-serve-admin.md
+++ b/docs/talos/reference/cli/talos-serve-admin.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos serve admin
Start the admin plane server (management only)
@@ -17,10 +18,11 @@ Start the admin plane server (management only)
Starts the admin plane server for API key and network management.
-This mode runs only the management endpoints for administrative operations.
-It's designed for internal tools, CI/CD, and administrative access.
+This mode runs only the management endpoints for administrative operations. It's designed for internal tools, CI/CD, and
+administrative access.
Features:
+
- Full read/write database access
- API key creation, rotation, revocation
- Network management
@@ -52,5 +54,4 @@ talos serve admin [flags]
### See also
-* [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
-
+- [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/cli/talos-serve-check.md b/docs/talos/reference/cli/talos-serve-check.md
index 33bbef15c4..6cf5e9192b 100644
--- a/docs/talos/reference/cli/talos-serve-check.md
+++ b/docs/talos/reference/cli/talos-serve-check.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos serve check
Start the data plane server (verification only)
@@ -17,8 +18,8 @@ Start the data plane server (verification only)
Starts the data plane server for API key and token verification.
-This mode runs only the verification endpoints with caching for optimal read performance.
-It's designed for edge deployments and high-throughput verification workloads.
+This mode runs only the verification endpoints with caching for optimal read performance. It's designed for edge deployments and
+high-throughput verification workloads.
Cache configuration is read from the config file (cache.type, cache.ttl, etc.)
@@ -47,5 +48,4 @@ talos serve check [flags]
### See also
-* [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
-
+- [talos serve](talos-serve.md) Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/cli/talos-serve.md b/docs/talos/reference/cli/talos-serve.md
index 8f6eb9f6aa..aab2d95c97 100644
--- a/docs/talos/reference/cli/talos-serve.md
+++ b/docs/talos/reference/cli/talos-serve.md
@@ -9,6 +9,7 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos serve
Start the Ory Talos server (all-in-one mode)
@@ -20,6 +21,7 @@ Starts the HTTP server for the API key service in all-in-one mode.
This mode runs both admin plane (management) and data plane (verification) in a single process.
For production deployments with high-throughput verification workloads, consider using:
+
- `serve check` for data plane only (verification with caching)
- `serve admin` for admin plane only (management operations)
@@ -48,7 +50,6 @@ talos serve [flags]
### See also
-* [talos](talos.md) Multi-tenant API key management service
-* [talos serve admin](talos-serve-admin.md) - Start the admin plane server (management only)
-* [talos serve check](talos-serve-check.md) - Start the data plane server (verification only)
-
+- [talos](talos.md) Multi-tenant API key management service
+- [talos serve admin](talos-serve-admin.md) - Start the admin plane server (management only)
+- [talos serve check](talos-serve-check.md) - Start the data plane server (verification only)
diff --git a/docs/talos/reference/cli/talos.md b/docs/talos/reference/cli/talos.md
index 9e5ca65ecb..b04675b900 100644
--- a/docs/talos/reference/cli/talos.md
+++ b/docs/talos/reference/cli/talos.md
@@ -9,17 +9,16 @@ This file is auto-generated.
To improve this file please make your change against the appropriate "./cmd/*.go" file.
-->
+
## talos
Multi-tenant API key management service
### Synopsis
-Ory Talos manages the full lifecycle of API credentials: issuing keys,
-verifying them at low latency, deriving short-lived JWT or macaroon tokens,
-and revoking access. It exposes a separate admin plane (issue, rotate,
-revoke, derive) and data plane (verify, self-revoke) so each can be scaled
-and secured independently.
+Ory Talos manages the full lifecycle of API credentials: issuing keys, verifying them at low latency, deriving short-lived JWT or
+macaroon tokens, and revoking access. It exposes a separate admin plane (issue, rotate, revoke, derive) and data plane (verify,
+self-revoke) so each can be scaled and secured independently.
### Options
@@ -31,9 +30,8 @@ and secured independently.
### See also
-* [talos jwk](talos-jwk.md) - Generate JSON Web Keys (JWK/JWKS)
-* [talos keys](talos-keys.md) - Manage API keys
-* [talos migrate](talos-migrate.md) - Database migration tools
-* [talos proxy](talos-proxy.md) - Start the edge proxy for caching verification requests
-* [talos serve](talos-serve.md) - Start the Ory Talos server (all-in-one mode)
-
+- [talos jwk](talos-jwk.md) - Generate JSON Web Keys (JWK/JWKS)
+- [talos keys](talos-keys.md) - Manage API keys
+- [talos migrate](talos-migrate.md) - Database migration tools
+- [talos proxy](talos-proxy.md) - Start the edge proxy for caching verification requests
+- [talos serve](talos-serve.md) - Start the Ory Talos server (all-in-one mode)
diff --git a/docs/talos/reference/config.md b/docs/talos/reference/config.mdx
similarity index 98%
rename from docs/talos/reference/config.md
rename to docs/talos/reference/config.mdx
index 3f74f0089f..68d6b0a23c 100644
--- a/docs/talos/reference/config.md
+++ b/docs/talos/reference/config.mdx
@@ -5,27 +5,25 @@ description: Auto-generated configuration reference from JSON Schema
# Configuration reference
-This page is auto-generated from the
-[configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
+This page is auto-generated from the [configuration schema](https://github.com/ory/talos/blob/main/spec/config.schema.json).
Required top-level keys: `credentials`, `secrets`
## Environment variables
-Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and
-converts dot-separated config paths to uppercase with underscores:
+Every configuration key can be set via an environment variable. Talos uses the `TALOS_` prefix and converts dot-separated config
+paths to uppercase with underscores:
```
TALOS__
```
-Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port`
-becomes `TALOS_SERVE_HTTP_PORT`.
+Replace dots (`.`) with underscores (`_`) and convert to uppercase. For example, `serve.http.port` becomes
+`TALOS_SERVE_HTTP_PORT`.
### Array values
-For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed
-variables:
+For array-typed config keys (like `secrets.hmac.retired`), use comma separation or indexed variables:
```bash
# Comma-separated
diff --git a/docs/talos/reference/error-codes.md b/docs/talos/reference/error-codes.md
index b519ac3baf..c9cc5094bb 100644
--- a/docs/talos/reference/error-codes.md
+++ b/docs/talos/reference/error-codes.md
@@ -8,9 +8,8 @@ description: HTTP and gRPC error codes returned by the Talos API
# Error codes
-Talos returns structured error responses following the [herodot](https://github.com/ory/herodot)
-error format. Every error response includes an `id`, HTTP status code, status text, and a
-human-readable message.
+Talos returns structured error responses following the [herodot](https://github.com/ory/herodot) error format. Every error
+response includes an `id`, HTTP status code, status text, and a human-readable message.
## Error response format
@@ -97,5 +96,4 @@ The `BatchImportAPIKeys` response includes per-item error codes:
- **4xx errors**: Fix the request and retry. Do not retry without changes.
- **409 Conflict**: Check if the resource already exists or is in an incompatible state.
- **5xx errors**: Retry with exponential backoff and jitter.
-- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After`
- header value if present.
+- **503 Service Unavailable**: The server is temporarily overloaded. Retry after the `Retry-After` header value if present.
diff --git a/docs/talos/reference/events.md b/docs/talos/reference/events.md
index 26b5d8751d..53c89a63c2 100644
--- a/docs/talos/reference/events.md
+++ b/docs/talos/reference/events.md
@@ -8,12 +8,10 @@ description: Structured audit events emitted by Talos via OpenTelemetry
# Audit events
-Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle
-operations. Events are attached to the active OTEL span and forwarded to any configured OTEL
-collector. They are never persisted locally.
+Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle operations. Events are attached to
+the active OTEL span and forwarded to any configured OTEL collector. They are never persisted locally.
-Each event carries a set of structured attributes that provide context about the operation, the
-actor, and the affected resource.
+Each event carries a set of structured attributes that provide context about the operation, the actor, and the affected resource.
## Event types
@@ -50,9 +48,9 @@ Each event carries the following OTEL span event attributes:
## Dynamic metadata attributes
-The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys
-are prefixed with `metadata.` in OTEL attributes. For example, a metadata entry
-`{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with value `jwt`.
+The `metadata.*` prefix supports arbitrary key-value pairs for event-specific context. Metadata keys are prefixed with `metadata.`
+in OTEL attributes. For example, a metadata entry `{"token_type": "jwt"}` becomes the OTEL attribute `metadata.token_type` with
+value `jwt`.
Metadata is optional and varies by event type. Common metadata keys include:
@@ -75,5 +73,4 @@ events.New(events.EventAPIKeyCreated).
Emit(ctx, emitter)
```
-Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently
-dropped.
+Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently dropped.
diff --git a/docs/talos/reference/index.md b/docs/talos/reference/index.md
index 41df753a2c..969be7c803 100644
--- a/docs/talos/reference/index.md
+++ b/docs/talos/reference/index.md
@@ -13,7 +13,7 @@ Technical reference documentation for Ory Talos.
## Configuration
-- [Configuration reference](config.md) — all configuration keys with types and defaults
+- [Configuration reference](config.mdx) — all configuration keys with types and defaults
## Technical details
diff --git a/docs/talos/reference/token-format.md b/docs/talos/reference/token-format.md
index 626ff6c3bf..4b2bf12170 100644
--- a/docs/talos/reference/token-format.md
+++ b/docs/talos/reference/token-format.md
@@ -23,12 +23,12 @@ prod_v1_5Z7Hn9K3mPqRtVwXyBcDeFgHiJkLmNoPqRsTuVwXyZ_AbC3XyZ789e
### Components
-| Component | Length | Description |
-| ------------ | ----------- | ----------------------------------------------------------------------------------------------------------- |
-| `prefix` | 1-16 chars | User-defined label (e.g., `prod`, `dev`, `test`). Set via `credentials.api_keys.prefix.current` in config. |
-| `v1` | 2 chars | Format version identifier |
-| `identifier` | ~64 chars | Base58-encoded `timestamp:uuid` payload |
-| `checksum` | ~44 chars | Full 32-byte HMAC-SHA256 over `prefix_v1_identifier_`, Base58-encoded |
+| Component | Length | Description |
+| ------------ | ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `prefix` | 1-16 chars | User-defined label (e.g., `prod`, `dev`, `test`). Set via `credentials.api_keys.prefix.current` in config. |
+| `v1` | 2 chars | Format version identifier |
+| `identifier` | ~64 chars | Base58-encoded `timestamp:uuid` payload |
+| `checksum` | ~44 chars | Full 32-byte HMAC-SHA256 over `prefix_v1_identifier_`, Base58-encoded |
### Identifier encoding
@@ -37,9 +37,8 @@ The identifier is a Base58 encoding of `timestamp:uuid`:
- **Timestamp**: Unix epoch seconds (int64). Embedded at key creation time.
- **UUID**: UUID v4 (36 chars with hyphens). Used as the `key_id` for database lookup.
-Base58 encoding uses the Bitcoin alphabet
-(`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually ambiguous
-characters (`0`, `O`, `I`, `l`).
+Base58 encoding uses the Bitcoin alphabet (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`), which excludes visually
+ambiguous characters (`0`, `O`, `I`, `l`).
### Checksum verification
@@ -48,8 +47,8 @@ The checksum is computed over the payload `prefix_v1_identifier_`:
1. Compute HMAC-SHA256 using the current HMAC secret (`secrets.hmac.current`)
2. Base58-encode the full 32-byte digest (no truncation)
-During verification, all configured secrets (current + retired) are tried in order. This supports
-secret rotation without invalidating existing keys.
+During verification, all configured secrets (current + retired) are tried in order. This supports secret rotation without
+invalidating existing keys.
### Credential routing
@@ -64,8 +63,7 @@ When a credential is submitted for verification, Talos identifies the credential
## Imported key format
-Imported keys have no format requirements. Any string credential can be imported. Talos stores a
-tenant-scoped hash:
+Imported keys have no format requirements. Any string credential can be imported. Talos stores a tenant-scoped hash:
```
SHA-512/256(network_id + 0x00 + raw_key)
@@ -83,25 +81,23 @@ Derived tokens produced as JWTs follow the standard JWT format:
eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature
```
-Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm
-is determined by the `alg` field in the JWK (EdDSA or RS256).
+Claims include the parent key's `key_id`, `actor_id`, scopes, and expiration. The signing algorithm is determined by the `alg`
+field in the JWK (EdDSA or RS256).
#### Signing key selection (`kid` hint)
-The data plane resolves the active signing key on every derive request. The `kid` header in the
-issued JWT identifies which JWK from the configured JWKS produced the signature.
+The data plane resolves the active signing key on every derive request. The `kid` header in the issued JWT identifies which JWK
+from the configured JWKS produced the signature.
Resolution order:
-1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK whose `kid`
- matches. If no JWK has that `kid`, signing fails with `InternalError` and the requested
- `signing_key_id` appears in the error details.
+1. If `credentials.derived_tokens.jwt.signing_key_id` is set, Talos selects the JWK whose `kid` matches. If no JWK has that `kid`,
+ signing fails with `InternalError` and the requested `signing_key_id` appears in the error details.
2. Otherwise, Talos prefers the first key with `"use": "sig"`.
3. Otherwise, Talos returns the first key in the JWKS.
-Set `signing_key_id` explicitly in production so rotating signing material becomes a config change
-rather than a JWKS-ordering side effect. In multi-tenant deployments the JWKS resolves per tenant
-via the contextualizer; the `kid` hint is also per-tenant.
+Set `signing_key_id` explicitly in production so rotating signing material becomes a config change rather than a JWKS-ordering
+side effect. In multi-tenant deployments the JWKS resolves per tenant via the contextualizer; the `kid` hint is also per-tenant.
### Macaroon
@@ -111,13 +107,13 @@ Macaroon tokens use a configurable prefix:
_v1_
```
-The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`).
-The data section contains the macaroon identifier and signature.
+The prefix is configured via `credentials.derived_tokens.macaroon.prefix.current` (default: `mc`). The data section contains the
+macaroon identifier and signature.
## ID formats
-| Context | Format | Length | Example |
-| ------------------ | ----------------------- | --------- | -------------------------------------- |
-| Database storage | UUID v4 string | 36 chars | `550e8400-e29b-41d4-a716-446655440000` |
+| Context | Format | Length | Example |
+| ------------------ | ----------------------- | --------- | -------------------------------------------- |
+| Database storage | UUID v4 string | 36 chars | `550e8400-e29b-41d4-a716-446655440000` |
| API key identifier | Base58-encoded | ~64 chars | `5Z7Hn9K3mPqRtVwXyBcDeFgHiJkLmNoPqRsTuVwXyZ` |
-| Imported key hash | Hex-encoded SHA-512/256 | 64 chars | `a1b2c3d4...` |
+| Imported key hash | Hex-encoded SHA-512/256 | 64 chars | `a1b2c3d4...` |