From 5edffbec7bdc2661ea3e3a1b63bf2090a088f26f Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Fri, 3 Jul 2026 20:44:01 +0200 Subject: [PATCH 1/2] feat: add API key management (Ory Talos) to the Ory Network docs Make API key management discoverable and usable for Ory Network readers: - Network intro, quickstart, and configuration pages under docs/network/talos using the Shared+shell pattern. - ConsoleLink routes and nav data for the Console API Keys section. - "API Key Management" category in the Network sidebar and Talos entries in every quickstarts picker variant. - Discoverability: intro, products overview, welcome cards, Network, OEL, and OSS landing pages, and the SDK page. Co-Authored-By: Claude Fable 5 --- docs/intro.mdx | 2 + docs/network/getting-started/index.mdx | 9 ++ docs/network/talos/configure.mdx | 99 ++++++++++++++++ docs/network/talos/index.mdx | 35 ++++++ docs/network/talos/quickstart.mdx | 111 ++++++++++++++++++ docs/oel/getting-started/index.mdx | 2 +- docs/oss/getting-started/index.mdx | 8 ++ docs/products/overview.mdx | 1 + docs/sdk.mdx | 3 +- sidebars-network.ts | 74 ++++++++++++ sidebars-quickstarts.ts | 38 ++++++ .../ConsoleLink/console-nav-data.ts | 24 ++++ src/components/ConsoleLink/console-routes.ts | 24 ++++ src/components/Shared/talos/index.mdx | 26 ++++ src/pages/_assets/welcome-content.tsx | 8 ++ 15 files changed, 462 insertions(+), 2 deletions(-) create mode 100644 docs/network/talos/configure.mdx create mode 100644 docs/network/talos/index.mdx create mode 100644 docs/network/talos/quickstart.mdx create mode 100644 src/components/Shared/talos/index.mdx diff --git a/docs/intro.mdx b/docs/intro.mdx index ba8470c2cc..a8661b6c4d 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -25,6 +25,8 @@ improves the safety of everyone: control (incl. RBAC and ABAC models) in any application. It's based on the open-source [Ory Keto Permission Server](https://github.com/ory/keto), which implements [Zanzibar: Google’s Consistent, Global Authorization System](https://research.google/pubs/pub48190/). +- Ory API key management lets you issue, import, verify, and revoke API keys for your own services and derive short-lived tokens. + It's based on the open-source [Ory Talos](https://github.com/ory/talos) API key management service. Ory develops and maintains many additional open-source projects. From an Ory Zero Trust Identity & Access Proxy [Ory Oathkeeper](https://github.com/ory/oathkeeper) to developer tooling [Ory Dockertest](https://github.com/ory/dockertest) to diff --git a/docs/network/getting-started/index.mdx b/docs/network/getting-started/index.mdx index c7b0d351f6..a25cba7a82 100644 --- a/docs/network/getting-started/index.mdx +++ b/docs/network/getting-started/index.mdx @@ -98,6 +98,15 @@ Ory Network incorporates the open-source [Ory Polis](https://www.ory.com/polis) - Simplified SSO flow by implementing SSO as a standard OAuth 2.0 flow, abstracting away the complexities of SAML. - Act as a SAML Identity Provider (IdP). +### API key management + +Ory Network incorporates [Ory Talos](https://www.ory.com/talos) and offers: + +- Issuing, rotating, and revoking API keys for your own APIs and services. +- Importing existing API keys and verifying any key with a single authenticated API call. +- Deriving short-lived JWT and macaroon tokens from long-lived keys. +- Per-key scopes, IP restrictions, and rate-limit policies, managed in the Ory Console. + ### Ory Console Ory Console is the management UI of Ory Network. diff --git a/docs/network/talos/configure.mdx b/docs/network/talos/configure.mdx new file mode 100644 index 0000000000..90174bf5ff --- /dev/null +++ b/docs/network/talos/configure.mdx @@ -0,0 +1,99 @@ +--- +id: configure +title: Configure API keys on Ory Network +sidebar_label: Configuration +--- + + + + + +On Ory Network there is no configuration file and no `TALOS_*` environment variables. API key settings live in your project +configuration: change them in the Ory Console or with the project APIs and the Ory CLI. + +:::note + +Configuration changes propagate asynchronously — allow a short delay before new settings affect key issuing and verification. + +::: + +## Ory Console + +Go to . The Configuration page has these sections: + +- **Rate limiting** — enable server-side rate-limit enforcement (subject to your plan). +- **Caching** — enable verification response caching and set the cache time-to-live (subject to your plan). +- **Lifespans** — the default and maximum lifetime of issued keys. +- **Key prefixes** — the current and retired secret prefixes, and the public current and retired prefixes. +- **Derived token defaults** — the token issuer, retired issuers, and the default lifetime of derived tokens. +- **JWT tokens** — rotate the JWT signing key, gracefully or with immediate revocation. +- **Macaroon tokens** — macaroon prefixes and HMAC secret rotation. + +## Ory CLI + +The project configuration uses the same JSON shape as the self-hosted configuration file, nested under `/services/talos`. Apply +the whole configuration object with `ory patch project`: + +```shell +ory patch project --project --workspace \ + --add '/services/talos={"config":{"credentials":{"api_keys":{"default_ttl":"168h","max_ttl":"8760h","prefix":{"current":"acme_ak"}},"derived_tokens":{"default_ttl":"1h"}},"cache":{"enabled":true,"ttl":"30s"},"rate_limit":{"enabled":true}}}' +``` + +Or import a full configuration file with `ory update project`: + +```shell +ory update project --project --workspace --file talos-config.json +``` + +where `talos-config.json` contains `{"services":{"talos":{"config":{...}}}}`. + +:::warning Caveats + +- `ory get project` does not return the API key configuration. Keep your desired configuration in a version-controlled file and + re-apply the whole object. +- Always use `--add '/services/talos=...'` with the complete configuration object. Deep patch paths such as + `--replace '/services/talos/config/credentials/issuer=...'` are not supported, because the project document returned by the API + contains no `services.talos` node to patch into. +- Use `--remove` to delete values. The `--delete` flag shown in some generated CLI examples does not exist. + +::: + +## Configuration reference + +These keys are configurable per project. The JSON paths are relative to `/services/talos/config`: + +| Setting | JSON path | Notes | +| ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ | +| Token issuer | `credentials.issuer`, `credentials.issuer_retired` | Must be the project URL or a registered custom domain. | +| Key lifespans | `credentials.api_keys.default_ttl`, `credentials.api_keys.max_ttl` | Durations such as `168h`. | +| Key prefixes | `credentials.api_keys.prefix.{current,retired,public_current,public_retired}` | Pattern `^[a-zA-Z0-9_]{1,16}$`. | +| Derived token lifetime | `credentials.derived_tokens.default_ttl` | Duration such as `1h`. | +| JWT signing keys | `credentials.derived_tokens.jwt.signing_keys.urls` | `base64://` literals only. | +| Macaroon prefixes | `credentials.derived_tokens.macaroon.prefix.{current,retired}` | | +| Caching | `cache.enabled`, `cache.ttl` | Subject to your plan. | +| Rate limiting | `rate_limit.enabled` | Subject to your plan. | + +Defaults on Ory Network differ from the self-hosted defaults in a few places: the issuer defaults to your project URL, issued keys +default to a lifetime of 168 hours (self-hosted keys have no expiry by default), the maximum lifetime is 17520 hours, and caching +is off by default with a 15 second time-to-live when enabled. + +## Managed by Ory + +Infrastructure settings — the database, `serve.*`, logging, tracing, the cache backend type, the rate-limit backend, last-used +tracking, multitenancy, clock skew, and the key quota (derived from your plan) — are operated by Ory. Setting them through the API +returns a warning or is ignored. + +## Secrets and rotation + +HMAC secrets and JWT signing keys are generated and stored by Ory; you never see or set them. Rotate them in the Console under +**API Keys** → **Configuration**: + +- **Graceful rotation** keeps retired secrets valid for verification during the transition. +- **Revoke** invalidates outstanding derived tokens immediately. + +## Plan gating + +Caching and server-side rate-limit enforcement require a plan that includes them; the Console shows an upgrade prompt when they +aren't available. See [plans and pricing](https://www.ory.com/pricing). + +Self-hosting? See the [configuration guide for self-hosted deployments](../../talos/operate/configure.md). diff --git a/docs/network/talos/index.mdx b/docs/network/talos/index.mdx new file mode 100644 index 0000000000..ae0e07b25c --- /dev/null +++ b/docs/network/talos/index.mdx @@ -0,0 +1,35 @@ +--- +id: index +title: API key management on Ory Network +sidebar_label: Introduction +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/talos/index.mdx" + + +``` + +## Enable API keys in your project + +API key management starts deactivated in every project. Open the + page and select **Enable API Keys**. This one-time step generates the project's HMAC +secret and JWT signing key and applies the default configuration. + +## Plans and quotas + +The number of active API keys, response caching, and server-side rate-limit enforcement depend on your +[subscription plan](https://www.ory.com/pricing). Issuing a key beyond your plan's quota returns HTTP 402 with the reason +`API_KEY_QUOTA_EXCEEDED`. + +## Next steps + +- Follow the [quickstart](./quickstart.mdx) to create a project, issue an API key, and verify it. +- Learn how to [configure API keys on Ory Network](./configure.mdx) with the Ory Console or the Ory CLI. +- Explore the guides for [issuing and verifying keys](../../talos/integrate/issue-and-verify.mdx), + [importing existing keys](../../talos/integrate/import-keys.mdx), and + [deriving short-lived tokens](../../talos/integrate/derive-tokens.mdx). diff --git a/docs/network/talos/quickstart.mdx b/docs/network/talos/quickstart.mdx new file mode 100644 index 0000000000..a38ae3f48e --- /dev/null +++ b/docs/network/talos/quickstart.mdx @@ -0,0 +1,111 @@ +--- +id: quickstart +title: Get started with API keys on Ory Network +sidebar_label: Quickstart +--- + + + + + +This quickstart takes you from an empty Ory Network project to issuing, verifying, and revoking an API key — using the Ory Console +and `curl`. No installation, database, or configuration file is required. + +## Create a project + +Sign up at [console.ory.com/registration](https://console.ory.com/registration) and create a free project, or use the +[Ory CLI](../../guides/cli/01_installation.mdx): + +```shell +ory create project --name "API keys demo" +``` + +Note the project slug — your project's API endpoint is `https://.projects.oryapis.com`. + +## Enable API keys + +Go to and select **Enable API Keys**. This one-time step generates the project's HMAC +secret and JWT signing key and applies the defaults: key prefix `ory_ak`, default key lifetime of 168 hours, and a maximum +lifetime of 17520 hours. + +## Get an admin credential + +:::info Two kinds of keys + +The keys you manage in the **API Keys** section are your product's API keys — credentials you issue to your own users and +services, with the `ory_ak_` prefix. To call the management API itself, you need an **Ory Network project API key** with the +`ory_pat_` prefix. Create one under **Project settings → API Keys** at +[console.ory.com/projects/current/developers](https://console.ory.com/projects/current/developers). + +::: + +Export your project slug and project API key: + +```shell +export PROJECT_SLUG= +export ORY_PAT=ory_pat_... +``` + +## Issue an API key + +In the Console, go to **API Keys** → **Keys** and select **Issue new key**: set a name and an optional expiry, then copy the +secret from the dialog — it is shown only once and starts with `ory_ak_`. + +Or issue a key with the API: + +```shell +curl -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/issuedApiKeys" \ + -H "Authorization: Bearer $ORY_PAT" \ + -H "Content-Type: application/json" \ + -d '{"name": "my-first-key"}' +``` + +The response returns HTTP 201 with the one-time `secret` and the key's ID in `issued_api_key.key_id`. Export both for the next +steps: + +```shell +export API_KEY=ory_ak_... +export KEY_ID= +``` + +## Verify the key + +In the Console, go to **API Keys** → **Playground** and paste the secret. Or verify with the API: + +```shell +curl -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/apiKeys:verify" \ + -H "Authorization: Bearer $ORY_PAT" \ + -H "Content-Type: application/json" \ + -d '{"credential": "'"$API_KEY"'"}' +``` + +The response contains `"is_valid": true`. Verification is an authenticated admin call on Ory Network: it confirms whether a +credential is valid and returns its metadata, so it requires the project API key like every other `/admin/` endpoint. + +## Revoke and re-verify + +Revoke the key from its row menu in **API Keys** → **Keys**, or with the API: + +```shell +curl -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/issuedApiKeys/$KEY_ID:revoke" \ + -H "Authorization: Bearer $ORY_PAT" +``` + +The call returns HTTP 204. Run the verify request again: the response now contains `"is_valid": false` and an `error_code`. + +Key holders can also revoke their own key without a project API key by proving possession of the secret — see +[self-revocation](../../talos/integrate/self-revocation.mdx). + +## Next steps + +- [Configure API keys on Ory Network](./configure.mdx) — lifespans, prefixes, caching, and secret rotation via Console or CLI. +- [Derive short-lived tokens](../../talos/integrate/derive-tokens.mdx) from long-lived keys. +- [Import existing keys](../../talos/integrate/import-keys.mdx) from another system. +- Browse the [API reference](../../talos/reference/api/ory-talos-api.info.mdx). + +:::note + +Issuing keys beyond your plan's quota returns HTTP 402 with the reason `API_KEY_QUOTA_EXCEEDED`. Quotas depend on your +[subscription plan](https://www.ory.com/pricing). + +::: diff --git a/docs/oel/getting-started/index.mdx b/docs/oel/getting-started/index.mdx index 4a0c0193d2..71ae06f23e 100644 --- a/docs/oel/getting-started/index.mdx +++ b/docs/oel/getting-started/index.mdx @@ -3,7 +3,7 @@ title: Introduction to Ory Enterprise License --- The Ory Enterprise License (OEL) is a commercial license designed for businesses and organizations that rely on Ory's open-source -identity and access control software (Ory Hydra, Ory Kratos, Ory Keto, Ory Oathkeeper, and Ory Polis) in production and +identity and access control software (Ory Hydra, Ory Kratos, Ory Keto, Ory Oathkeeper, Ory Polis, and Ory Talos) in production and mission-critical environments. It grants access to enterprise-grade features, dedicated support, and builds optimized for stability, security, and scalability. diff --git a/docs/oss/getting-started/index.mdx b/docs/oss/getting-started/index.mdx index a4991bf9d4..81ace2eeff 100644 --- a/docs/oss/getting-started/index.mdx +++ b/docs/oss/getting-started/index.mdx @@ -70,6 +70,14 @@ Ory Keto is able to authenticate different types of credentials (for example OAu Tokens, ...) and allows you to define advanced permission rules ("Access Control Policies"). And there's of course an endpoint that tells you if a certain set of credentials (for example an OAuth 2.0 Access Token) is allowed to modify that blog post. +## Ory Talos + +Your APIs have users of their own: services, scripts, and AI agents that authenticate with API keys instead of a login screen. +Issuing those keys securely, verifying them on every request, and revoking them when they leak is its own problem — and Ory Talos +solves it. Issue and import API keys, verify them with a single call, derive short-lived JWT or macaroon tokens from long-lived +keys, and let key holders revoke a compromised key themselves. Start with the [Ory Talos documentation](../../talos/index.md) or +jump straight into the [open-source quickstart](../../talos/quickstart/open-source.mdx). + ## Ory Polis ![Ory Polis](https://raw.githubusercontent.com/ory/meta/master/static/logos/logo-polis.svg) diff --git a/docs/products/overview.mdx b/docs/products/overview.mdx index 422a1390a8..ce5e5db671 100644 --- a/docs/products/overview.mdx +++ b/docs/products/overview.mdx @@ -46,6 +46,7 @@ Choose Ory products based on the specific identity, authorization, or access con | Delegated, Scope-based Authorization & Token Issuance | Which application can act on behalf of a user, and with what level of access? | **Ory Hydra** Implements OAuth2 and OpenID Connect to issue access and ID tokens with scopes. Delegates user login to Kratos or another IdP, enabling SSO and API access across apps and services. | | Enterprise Federation & Single Sign-On (SSO) | How can enterprise customers sign in with their corporate identity provider? | **Ory Polis** Provides enterprise SSO by connecting apps to SAML and OIDC identity providers. Bridges legacy SAML into modern OAuth2 flows and supports SCIM directory sync for automated user and group provisioning. | | Proxy Access Control (Enforcement) | Should this request be allowed to reach the API right now? | **Ory Oathkeeper** Acts as a proxy-based enforcement layer in front of APIs and services, validating credentials and applying authorization decisions before traffic reaches your application. | +| API Key Management & Machine Credentials | How do services, agents, and machines authenticate to my APIs? | **Ory Talos** Issues, imports, verifies, and revokes API keys for your own APIs, and derives short-lived JWT or macaroon tokens from long-lived keys. | ## From products to solutions diff --git a/docs/sdk.mdx b/docs/sdk.mdx index 61f1ac4e64..b0c1d23f83 100644 --- a/docs/sdk.mdx +++ b/docs/sdk.mdx @@ -4,7 +4,8 @@ title: Software Development Kits (SDKs) for Ory sidebar_label: SDKs --- -The Ory SDK allows for integration with Ory services, including **Ory Identities**, **Ory Permissions**, and **Ory OAuth2**. +The Ory SDK allows for integration with Ory services, including **Ory Identities**, **Ory Permissions**, **Ory OAuth2**, and **API +key management (Ory Talos)**. Before using the SDK, consult the Ory [REST](./reference/api.mdx) API documentation, which includes code samples and examples for various programming languages. diff --git a/sidebars-network.ts b/sidebars-network.ts index 180cda8fc3..94d603189f 100644 --- a/sidebars-network.ts +++ b/sidebars-network.ts @@ -3,9 +3,24 @@ import { SidebarItem, SidebarItemConfig, } from "@docusaurus/plugin-content-docs/src/sidebars/types" +import talosApiSidebar from "./docs/talos/reference/api/sidebar" type SidebarItemsConfig = SidebarItemConfig[] +// The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. +// Lift the methods into a single "API reference" category linked to the overview page so the +// navigation reads cleanly instead of exposing the raw OpenAPI tag name. +const talosApiReference = { + type: "category", + label: "API reference", + link: { type: "doc", id: "talos/reference/api/ory-talos-api" }, + items: talosApiSidebar.flatMap((item: any) => + typeof item === "object" && "items" in item && Array.isArray(item.items) + ? item.items + : [], + ), +} + const networkSidebar = [ { type: "category", @@ -818,6 +833,65 @@ const networkSidebar = [ }, ], }, + { + type: "category", + label: "API Key Management", + className: "sidebar-icon sidebar-icon-talos", + collapsed: true, + items: [ + "network/talos/index", + { + type: "category", + label: "Get started", + collapsed: false, + collapsible: false, + items: ["network/talos/quickstart", "network/talos/configure"], + }, + { + type: "category", + label: "Guides", + collapsed: false, + collapsible: 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: "Concepts", + collapsed: false, + collapsible: false, + link: { type: "doc", id: "talos/concepts/index" }, + items: [ + "talos/concepts/credential-types", + "talos/concepts/token-format", + "talos/concepts/security-model", + "talos/concepts/caching", + "talos/concepts/rate-limiting", + "talos/concepts/ip-restrictions", + ], + }, + { + type: "category", + label: "Reference", + collapsed: true, + items: [ + talosApiReference, + "talos/reference/token-format", + "talos/reference/error-codes", + ], + }, + ], + }, ], }, ] diff --git a/sidebars-quickstarts.ts b/sidebars-quickstarts.ts index 8eae48d6c9..2b70bf4771 100644 --- a/sidebars-quickstarts.ts +++ b/sidebars-quickstarts.ts @@ -60,6 +60,12 @@ const overviewAndNetwork = [ className: "sidebar-icon sidebar-icon-oathkeeper", items: ["network/oathkeeper/quickstarts/index"], }, + { + type: "category", + label: "API Key Management", + className: "sidebar-icon sidebar-icon-talos", + items: ["network/talos/quickstart"], + }, ], }, { @@ -126,6 +132,14 @@ const overviewAndNetwork = [ "oel/oathkeeper/quickstarts/configure-deploy", ], }, + { + type: "category", + label: "Ory Talos", + collapsed: true, + collapsible: true, + className: "sidebar-icon sidebar-icon-talos", + items: ["talos/quickstart/docker-commercial"], + }, ], }, { @@ -192,6 +206,14 @@ const overviewAndNetwork = [ "oss/oathkeeper/quickstarts/configure-deploy", ], }, + { + type: "category", + label: "Ory Talos", + collapsed: true, + collapsible: true, + className: "sidebar-icon sidebar-icon-talos", + items: ["talos/quickstart/open-source"], + }, ], }, ] @@ -269,6 +291,14 @@ const overviewAndOel = [ "oel/oathkeeper/quickstarts/configure-deploy", ], }, + { + type: "category", + label: "Ory Talos", + collapsed: true, + collapsible: true, + className: "sidebar-icon sidebar-icon-talos", + items: ["talos/quickstart/docker-commercial"], + }, ], }, ] @@ -343,6 +373,14 @@ const overviewAndOss = [ "oss/oathkeeper/quickstarts/configure-deploy", ], }, + { + type: "category", + label: "Ory Talos", + collapsed: true, + collapsible: true, + className: "sidebar-icon sidebar-icon-talos", + items: ["talos/quickstart/open-source"], + }, ], }, ] diff --git a/src/components/ConsoleLink/console-nav-data.ts b/src/components/ConsoleLink/console-nav-data.ts index f04baa230c..75475e1c27 100644 --- a/src/components/ConsoleLink/console-nav-data.ts +++ b/src/components/ConsoleLink/console-nav-data.ts @@ -176,6 +176,25 @@ export const permissionsPaths: Path[] = [ }, ] +export const apiKeysPaths: Path[] = [ + { + title: "Keys", + href: routes.project.apiKeys.keys.route, + }, + { + title: "Imported", + href: routes.project.apiKeys.imported.route, + }, + { + title: "Playground", + href: routes.project.apiKeys.playground.route, + }, + { + title: "Configuration", + href: routes.project.apiKeys.configuration.route, + }, +] + export const projectSettingsPaths: Path[] = [ { title: "Overview", @@ -253,6 +272,11 @@ export const projectPaths: RootPath[] = [ href: routes.project.oauthConfiguration.route, paths: oauthPaths, }, + { + title: "API Keys", + href: routes.project.apiKeys.route, + paths: apiKeysPaths, + }, { title: "Permissions", href: routes.project.permissions.configuration.route, diff --git a/src/components/ConsoleLink/console-routes.ts b/src/components/ConsoleLink/console-routes.ts index 6474724ae7..40af62040a 100644 --- a/src/components/ConsoleLink/console-routes.ts +++ b/src/components/ConsoleLink/console-routes.ts @@ -156,6 +156,30 @@ export const routes = { `/projects/${project}/permissions/configuration`, }, }, + // The route keys follow the Console nav labels (Keys, Imported, + // Playground, Configuration); the Console app's own sitemap keys are + // `native` and `settings` for the first and last route — this mismatch + // is intentional, do not "fix" it. + apiKeys: { + route: "/projects/[project]/api-keys/native", + href: (project: string) => `/projects/${project}/api-keys/native`, + keys: { + route: "/projects/[project]/api-keys/native", + href: (project: string) => `/projects/${project}/api-keys/native`, + }, + imported: { + route: "/projects/[project]/api-keys/imported", + href: (project: string) => `/projects/${project}/api-keys/imported`, + }, + playground: { + route: "/projects/[project]/api-keys/playground", + href: (project: string) => `/projects/${project}/api-keys/playground`, + }, + configuration: { + route: "/projects/[project]/api-keys/settings", + href: (project: string) => `/projects/${project}/api-keys/settings`, + }, + }, identitySchema: { route: "/projects/[project]/identity-schema", href: (project: string) => `/projects/${project}/identity-schema`, diff --git a/src/components/Shared/talos/index.mdx b/src/components/Shared/talos/index.mdx new file mode 100644 index 0000000000..2672805af5 --- /dev/null +++ b/src/components/Shared/talos/index.mdx @@ -0,0 +1,26 @@ +API keys are long-lived credentials for services, agents, and other machine +callers of your APIs. API key management on Ory Network — powered by the +open-source [Ory Talos](https://www.ory.com/talos) API key management service — +handles the full lifecycle of these credentials: issuing keys, verifying them at +low latency, deriving short-lived tokens, and revoking access. + +With API key management, you can: + +- Issue and manage API keys for your own APIs and services, with the one-time + secret shown only at creation. +- Import existing API keys from another system, individually or in batches, and + manage them like native keys. +- Verify any key — single or in batches — with one authenticated API call that + returns the key's status and metadata. +- Derive short-lived JWT or macaroon tokens from long-lived keys and verify the + JWTs locally against a published JWKS, without a round-trip. +- Let key holders revoke their own compromised keys through an unauthenticated + proof-of-possession endpoint. +- Attach scopes, expiry times, IP CIDR restrictions, and rate-limit policies to + every key, managed in the Ory Console. + +To understand the credential model — issued keys, imported keys, and derived +tokens — see +[credential types](../../../../docs/talos/concepts/credential-types). For the +trust boundaries and threat model, see the +[security model](../../../../docs/talos/concepts/security-model). diff --git a/src/pages/_assets/welcome-content.tsx b/src/pages/_assets/welcome-content.tsx index 3596d05231..0d978d10e1 100644 --- a/src/pages/_assets/welcome-content.tsx +++ b/src/pages/_assets/welcome-content.tsx @@ -116,6 +116,14 @@ export const authorizationSecurity: { languageLogoAlt: "Service account icon", docs: "/docs/oauth2-oidc/client-credentials", }, + { + title: "Manage API keys", + description: + "Issue, verify, and revoke API keys for services and AI agents", + language: "token", + languageLogoAlt: "API key icon", + docs: "/docs/network/talos/quickstart", + }, ], } From 50cbab0720109af7e40ba7fb335f68708f05af1d Mon Sep 17 00:00:00 2001 From: aeneasr <3372410+aeneasr@users.noreply.github.com> Date: Sat, 4 Jul 2026 12:32:08 +0200 Subject: [PATCH 2/2] fix: correct API key activation and SDK availability statements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New projects get their Talos HMAC secret and JWT signing key at creation (backoffice setSecrets), so the Enable API Keys button only appears on projects created before the launch — describe both states instead of an unconditional activation step. Soften the SDK page so it does not imply the currently published @ory/client already exports the API keys client, and clarify the max_ttl value in the CLI example. Co-Authored-By: Claude Fable 5 --- docs/network/talos/configure.mdx | 2 ++ docs/network/talos/index.mdx | 8 ++++---- docs/network/talos/quickstart.mdx | 11 +++++++---- docs/sdk.mdx | 4 ++-- 4 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/network/talos/configure.mdx b/docs/network/talos/configure.mdx index 90174bf5ff..42c095b182 100644 --- a/docs/network/talos/configure.mdx +++ b/docs/network/talos/configure.mdx @@ -39,6 +39,8 @@ ory patch project --project --workspace \ --add '/services/talos={"config":{"credentials":{"api_keys":{"default_ttl":"168h","max_ttl":"8760h","prefix":{"current":"acme_ak"}},"derived_tokens":{"default_ttl":"1h"}},"cache":{"enabled":true,"ttl":"30s"},"rate_limit":{"enabled":true}}}' ``` +The example lowers the maximum key lifetime to one year (`8760h`); the Network default is `17520h`. + Or import a full configuration file with `ory update project`: ```shell diff --git a/docs/network/talos/index.mdx b/docs/network/talos/index.mdx index ae0e07b25c..0e3287f403 100644 --- a/docs/network/talos/index.mdx +++ b/docs/network/talos/index.mdx @@ -14,11 +14,11 @@ import MyPartial from "@site/src/components/Shared/talos/index.mdx" ``` -## Enable API keys in your project +## API key setup -API key management starts deactivated in every project. Open the - page and select **Enable API Keys**. This one-time step generates the project's HMAC -secret and JWT signing key and applies the default configuration. +New projects come with API key management ready to use: Ory generates the project's HMAC secret and JWT signing key when the +project is created and applies the default configuration. Projects created before API key management launched show an **Enable API +Keys** button on the page instead — selecting it runs the same one-time setup. ## Plans and quotas diff --git a/docs/network/talos/quickstart.mdx b/docs/network/talos/quickstart.mdx index a38ae3f48e..ad9d554cc0 100644 --- a/docs/network/talos/quickstart.mdx +++ b/docs/network/talos/quickstart.mdx @@ -22,11 +22,14 @@ ory create project --name "API keys demo" Note the project slug — your project's API endpoint is `https://.projects.oryapis.com`. -## Enable API keys +## Open API keys in the Console -Go to and select **Enable API Keys**. This one-time step generates the project's HMAC -secret and JWT signing key and applies the defaults: key prefix `ory_ak`, default key lifetime of 168 hours, and a maximum -lifetime of 17520 hours. +Go to . New projects come with API key management ready to use: Ory generates the +project's HMAC secret and JWT signing key at project creation and applies the defaults — key prefix `ory_ak`, default key lifetime +of 168 hours, and a maximum lifetime of 17520 hours. + +If your project was created before API key management launched, the page shows **Enable API Keys** instead. Select it to run the +same one-time setup. ## Get an admin credential diff --git a/docs/sdk.mdx b/docs/sdk.mdx index b0c1d23f83..1adab277ed 100644 --- a/docs/sdk.mdx +++ b/docs/sdk.mdx @@ -4,8 +4,8 @@ title: Software Development Kits (SDKs) for Ory sidebar_label: SDKs --- -The Ory SDK allows for integration with Ory services, including **Ory Identities**, **Ory Permissions**, **Ory OAuth2**, and **API -key management (Ory Talos)**. +The Ory SDK allows for integration with Ory services, including **Ory Identities**, **Ory Permissions**, and **Ory OAuth2**. +Recent SDK releases also include the **API key management (Ory Talos)** client. Before using the SDK, consult the Ory [REST](./reference/api.mdx) API documentation, which includes code samples and examples for various programming languages.