Skip to content

feat: add API key management (Ory Talos) to the Ory Network docs#2661

Draft
aeneasr wants to merge 2 commits into
masterfrom
talos-network-docs
Draft

feat: add API key management (Ory Talos) to the Ory Network docs#2661
aeneasr wants to merge 2 commits into
masterfrom
talos-network-docs

Conversation

@aeneasr

@aeneasr aeneasr commented Jul 3, 2026

Copy link
Copy Markdown
Member

What changed

Ory Talos (API key management) is live on Ory Network but invisible in these docs. This PR adds the Network-facing surfaces (PR-3 of a three-PR sequence):

  • New pages under docs/network/talos/ using the Shared+shell pattern (src/components/Shared/talos/index.mdx):
    • Introduction — what API key management offers, one-time activation, plan gating.
    • Quickstart — create project → enable API keys → issue → verify → revoke, via Console and authenticated curl (ory_pat_ vs ory_ak_ disambiguation included; verify is an authenticated admin call, never public).
    • Configuration — Console sections, ory patch project --add '/services/talos=…' (whole object), caveats (ory get project omits the config; deep patch paths unsupported; --remove not --delete), per-project key reference with Network-default deltas, managed-by-Ory list, rotation semantics.
  • ConsoleLink: routes.project.apiKeys.{keys,imported,playground,configuration} + "API Keys" nav group between "OAuth 2" and "Permissions" (matches the shipped Console nav). npm run check-console-links passes — the Console pages resolve.
  • Sidebars: top-level "API Key Management" category in sidebars-network.ts (mixing the new shells with the existing talos/{integrate,concepts,reference} tree, Keto precedent; deliberately excludes operate/*, env-var config reference, and the talos CLI pages from the Network audience) + quickstarts picker entries for Network/OEL/OSS.
  • Discoverability: intro.mdx, products/overview.mdx, welcome cards, Network/OEL/OSS getting-started pages, sdk.mdx.

No existing URLs changed → no vercel.json redirects.

Sequencing

  • Companion source PR (monorepo): ory-corp/cloud#12679 — must merge first only for content freshness, not for this build.
  • The docs/talos/ whole-tree port ("PR-2") follows separately; the sidebar here references only pre-existing talos/* doc ids. Port contract change: never rsync the monorepo-generated reference/api/ into this repo — copy the spec to docs/talos/reference/api.json and regenerate with npx docusaurus clean-api-docs talos && npx docusaurus gen-api-docs talos.

Verification

  • npm run build — green, zero talos-related warnings (checked manually because onBrokenLinks: warn).
  • make format, npm run check-console-links — green. markdownlint: only baseline MD044 noise identical to the merged Keto shells.

Merge order (do not merge before the port)

sidebars-network.ts links talos/integrate/* and talos/concepts/* doc ids whose current copies under docs/talos/ are the pre-port tree — self-hosted-only content with no deployment-aware prerequisites. Merge order:

  1. Land monorepo PR ory-corp/cloud#12679 (Network-aware shared pages + prerequisites partial).
  2. Run the whole-tree port of talos/talos/docs/ into docs/talos/ (Task 5 procedure).
  3. Then merge this PR (or bundle the port into it).

Console screenshots are produced by the new e2epw screenshot rake (test/e2epw, pnpm run docs-screenshots + scripts/sync-docs-screenshots.sh) once the k3d cluster is up; embed them together with the images in docs/network/talos/_static/.

Remaining before un-drafting

  • Console screenshots for the quickstart/configuration pages (BrowserWindow), captured on a fresh project.
  • Live walkthrough of the quickstart curl set and the ory patch project round-trip (prose is code-verified against the spec, gateway rules, and backoffice tests).
  • Docs-team sign-off on the "API Key Management" label and sidebar placement.

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant