docs(api): pull AUTH.md through from the gateway, fix stale Stytch-era references - #52
Draft
bryanfawcett wants to merge 3 commits into
Draft
docs(api): pull AUTH.md through from the gateway, fix stale Stytch-era references#52bryanfawcett wants to merge 3 commits into
bryanfawcett wants to merge 3 commits into
Conversation
…ch-era references
The WorkOS sign-in docs still described return_to as unchecked and
pointed at /v1/auth/exchange, /v1/auth/refresh, and /v1/auth/otp/* —
all removed when WorkOS AuthKit became the sole auth provider. Updates:
- Explains return_to is validated against an allowlist, and shows how a
third-party app registers its own redirect origin via
PATCH /v1/api-keys/{id}/redirect-uris + client_id, instead of needing
its domain hardcoded into gateway config.
- Documents /callback's fail-closed default (400 unless
allow_direct_token_response=true is explicitly passed) instead of the
old "returns JSON when no return_to" description.
- Removes the retired /v1/auth/exchange, /v1/auth/refresh, and
/v1/auth/otp/* mentions from authentication.mdx and security.mdx's
rate-limit table; replaces with the real /v1/auth/workos/* limits.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
nyuchi-docs-mcp | b9a649a | Commit Preview URL Branch Preview URL |
Aug 02 2026, 08:23 AM |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
shamwari-docs-ai | b9a649a | Commit Preview URL Branch Preview URL |
Aug 02 2026, 08:23 AM |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
nyuchi-docs | b9a649a | Commit Preview URL Branch Preview URL |
Aug 02 2026, 08:24 AM |
A rendered MDX page requires an HTML parser; agents building against api.nyuchi.com need a single raw markdown file they can curl directly. Consolidates the WorkOS sign-in flow, the per-app client_id/redirect_uris registration steps, and the callback's fail-closed default (with an explicit warning against defaulting allow_direct_token_response to true) into site/public/AUTH.md, served at docs.nyuchi.com/AUTH.md. Linked from llms.txt so it's part of the site's discoverable machine-readable surface, alongside the existing rendered docs it mirrors.
public/AUTH.md was a hand-maintained duplicate of nyuchi/api-gateway's auth integration guide, with no way to stay in sync. api-gateway now serves it live at GET /AUTH.md (its docs/AUTH.md is the source); this adds scripts/sync-auth-md.mjs, wired into `pnpm build` right after generate:internal-paths, which fetches that endpoint and overwrites public/AUTH.md with it. Best-effort: if the fetch fails (network policy, gateway briefly down), it warns and leaves the committed copy in place rather than failing the whole docs build.
bryanfawcett
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion to
nyuchi/api-gateway#30(merged) and#32. The public WorkOS sign-in docs were out of date, and the agent-facing reference had no way to stay in sync with the actual gateway.return_toas effectively unchecked, and pointed at/v1/auth/exchange,/v1/auth/refresh, and/v1/auth/otp/*— all removed when WorkOS AuthKit became the sole auth provider.return_toregistration — this is a public, multi-tenant endpoint, so a third-party app now registers its own redirect origin on its own API key (PATCH /v1/api-keys/{id}/redirect-uris) and passesclient_idat/login.public/AUTH.mdstarted as a hand-maintained duplicate.nyuchi/api-gateway#32now serves it live atGET /AUTH.mdfromdocs/AUTH.md(the real source of truth, co-located with the code it describes) — this PR makes the docs site pull from there instead of hand-copying.Changes
site/scripts/sync-auth-md.mjs(new): fetcheshttps://api.nyuchi.com/AUTH.mdand overwritespublic/AUTH.mdwith it. Wired intopnpm buildright aftergenerate:internal-paths. Best-effort — if the fetch fails (network policy, gateway briefly down), it warns and leaves the committed fallback copy in place rather than failing the whole docs build. Override the source withAUTH_MD_SOURCE_URLif ever needed.public/AUTH.md: updated its own header note to say "don't hand-edit this, it's overwritten at build time" — kept as the fallback copy for when the fetch fails.api/authentication.mdx: documentsreturn_tovalidation, the new "Third-party apps: register your redirect origin" section,/callback's fail-closed default, and removes the retired-endpoint references (the OTP aside, the/v1/auth/refreshcall-to-action).api/api-keys.mdx: new "Register redirect URIs for hosted sign-in" section.api/security.mdx: rate-limit table now lists/v1/auth/workos/*instead of the removed OTP/exchange/refresh endpoints.Test plan
node scripts/sync-auth-md.mjslocally — confirmed it fails gracefully (network-restricted sandbox) and leaves the existingpublic/AUTH.mduntouched rather than corrupting itpnpm -r build) — will confirm the script runs cleanly in that environment and doesn't break the site build even if it can't reach the live gateway