Developer authentication

## Developer authentication

Developer authentication docs explain how API examples relate to a reader's Brothh session, publishable key, future secret key, and playground access. This page should be the first stop before any API endpoint that requires account context.

{% figure src="/docs-images/gitbook-developers-auth.png" alt="GitBook developer authentication page" caption="The developer authentication page explains signed-in docs context, placeholder credentials, and the current playground gate before a reader runs account-aware API examples." /%}

## Current gate

Secret-key issuance is still gated. Do not document a live secret-key reveal flow until the schema/API path exists. If an example needs a secret, use a clearly marked placeholder such as \`sk_test_demo_xxx\` and state that live secrets are not shown in GitBook yet.

## What to document

- Where a signed-in reader sees account context in GitBook.
- Which examples work anonymously and which require sign-in.
- Which viewer variables can appear in docs, such as seller or producer IDs.
- How playground requests are proxied through GitBook.
- How to avoid leaking server-side secrets in browser-rendered examples.

## Recovery

If a reader is signed out, route them to \`/auth/login?next=/developers/auth\`. If the viewer context cannot load, keep the page readable and show placeholders rather than failing the article render.

## Developer authentication

Developer authentication docs explain how API examples relate to a reader's Brothh session, publishable key, future secret key, and playground access. This page should be the first stop before any API endpoint that requires account context.

{% figure src="/docs-images/gitbook-developers-auth.png" alt="GitBook developer authentication page" caption="The developer authentication page explains signed-in docs context, placeholder credentials, and the current playground gate before a reader runs account-aware API examples." /%}

## Current gate

Secret-key issuance is still gated. Do not document a live secret-key reveal flow until the schema/API path exists. If an example needs a secret, use a clearly marked placeholder such as \`sk_test_demo_xxx\` and state that live secrets are not shown in GitBook yet.

## What to document

- Where a signed-in reader sees account context in GitBook.
- Which examples work anonymously and which require sign-in.
- Which viewer variables can appear in docs, such as seller or producer IDs.
- How playground requests are proxied through GitBook.
- How to avoid leaking server-side secrets in browser-rendered examples.

## Recovery

If a reader is signed out, route them to \`/auth/login?next=/developers/auth\`. If the viewer context cannot load, keep the page readable and show placeholders rather than failing the article render.