Documentation Reader

<x-wirekit::reading-shell
    :previewMode="true"
    bookmarkKey="documentation-reader-demo"
    :minimap="true"
    :meta="false"
    density="comfortable"
>
    <x-wirekit::prose>
        <header style="margin-bottom: 2rem;">
            <h1>API Reference: Authentication</h1>
            <x-wirekit::reading-meta :showRemaining="true" :wpm="200" />
        </header>
        <article>
            <h2 id="dr-overview">Overview</h2>
            <p>API authentication uses bearer tokens. Token rotation, scope handling, and rate-limit semantics are covered in the sub-sections below. The reading-shell composition here uses the comfortable density preset with the minimap toggle on — that gives you both the heading-level spine on the right and a paragraph-level density-overview alongside it.</p>
            <p>The minimap renders one stripe per item matched by <code>itemSelector</code> (default: <code>a, h2, h3, [data-minimap-item]</code>). On a docs page with 60+ paragraphs, the minimap gives a "you are here" overview of the whole page that the heading-level spine can't — heading-only TOCs lose granularity below the heading level.</p>
            <h3 id="dr-overview-tokens">Token Format</h3>
            <p>Tokens are 64-character hex strings prefixed with <code>sk_live_</code> or <code>sk_test_</code>. The prefix denotes the environment; the suffix is the random material. Tokens never expire automatically — rotation is a deliberate operation, not a background timer.</p>
            <p>Test-mode tokens scope to test-mode resources only. Live-mode tokens never collide with test data; the prefix is the only resolution mechanism. This avoids the worst-case "test code accidentally hits production" failure mode that token-suffix-only schemes don't prevent.</p>
            <h3 id="dr-overview-headers">Required Headers</h3>
            <p>Pass <code>Authorization: Bearer {token}</code> on every request. Both HTTP/1.1 and HTTP/2 are supported. Token rotation does not invalidate active long-poll connections — the connection-level auth is performed once at handshake.</p>
            <p>The token never appears in URL query strings or request paths. It only flows through the <code>Authorization</code> header. This keeps the token out of access logs, browser history, and cached upstream proxy entries.</p>
            <h2 id="dr-rotation">Token Rotation</h2>
            <p>Tokens never expire automatically — rotate manually via the dashboard or via the <code>POST /v1/tokens/rotate</code> endpoint. The dashboard is the recommended path for production rotation; the API endpoint is for automated rotation in CI / IaC pipelines.</p>
            <p>Rotation issues a new token, marks the old one as deprecated (still valid for 24 hours), and triggers a webhook to your registered URL. The 24-hour overlap is the recommended migration window — it covers a typical CI deploy cycle plus retry budget.</p>
            <h3 id="dr-rotation-rolling">Rolling Rotation</h3>
            <p>Issue a new token, deploy with both, then revoke the old one. This is the canonical zero-downtime rotation pattern — both tokens are valid simultaneously during the rolling window so any in-flight request signed with the old token still completes.</p>
            <p>Use the <code>X-Token-Generation</code> response header to track which token signed each response. CI canaries can compare the header against the expected new generation to confirm the rolling deploy reached every replica before revoking the old token.</p>
            <h4 id="dr-rotation-rolling-deploy">Deployment Window</h4>
            <p>Allow 5 minutes for caches to flush. Edge proxies cache the token-validation result for up to 60 seconds; the dashboard's "Revoke now" button bypasses the cache and forces immediate invalidation across every region.</p>
            <p>For zero-downtime rolling, sequence the revoke 5 minutes after the last replica deployed the new token. Earlier revoke risks a small slice of in-flight requests failing during the cache-flush window.</p>
            <h2 id="dr-scopes">Scopes</h2>
            <p>Scope tokens to specific operations to limit blast radius. A leaked read-only token cannot mutate state; a leaked customer-only token cannot enumerate other resources. Scopes are an essential defense-in-depth even when the token rotation cycle is fast.</p>
            <p>Each token can carry up to 32 scopes. The dashboard's scope picker shows the per-resource matrix (read / write / delete) — pick exactly what the token needs and nothing more. Token requests rejected for missing scope return HTTP 403 with a structured error body identifying the missing scope.</p>
            <h3 id="dr-scopes-read">Read Scopes</h3>
            <p>Read-only access to specific resources. <code>customers:read</code>, <code>orders:read</code>, <code>products:read</code> are the canonical three; lower-cardinality reads (e.g. <code>tax-rates:read</code>) get their own scopes for tighter control.</p>
            <p>Read scopes never grant access to webhook endpoints, internal admin operations, or audit logs. Each of those carries its own scope namespace (<code>webhooks:read</code>, <code>admin:read</code>, <code>audit:read</code>) — separate concerns get separate scopes.</p>
            <h3 id="dr-scopes-write">Write Scopes</h3>
            <p>Mutation access — use sparingly. <code>customers:write</code> grants both create and update; the destructive verb (<code>customers:delete</code>) is its own scope so least-privilege CI tokens can't accidentally delete records during a misfire.</p>
            <p>Write scopes implicitly grant the corresponding read scope. <code>customers:write</code> grants <code>customers:read</code>; you don't need to specify both. The implication runs only one direction — read scopes never grant write access.</p>
            <h2 id="dr-rate-limits">Rate Limits</h2>
            <p>Default 100 req/min per token; burst to 200 for short windows. The rate-limiter uses a token-bucket algorithm with a per-token state — each token has its own counter, so a leaked token can't exhaust your account-wide quota.</p>
            <p>Higher limits are available via the dashboard for verified accounts. Premium tiers ship with 1000 req/min default and 5000 req/min burst. The rate-limit headers (<code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code>, <code>X-RateLimit-Reset</code>) appear on every response so client SDKs can self-throttle without polling a separate quota endpoint.</p>
        </article>
    </x-wirekit::prose>
</x-wirekit::reading-shell>

{{-- Power-user composition: skip the shell, mount primitives directly --}}
<x-wirekit::reading-progress variant="primary" :milestones="true" />
<x-wirekit::reading-spine
    :levels="'2,3,4'"
    expand="always-md"
    :numbered="true"
    :fillSections="true"
    :backToTop="true"
>
    <x-slot:filter>
        <x-wirekit::input x-model="filter" placeholder="Filter sections..." size="sm" />
    </x-slot:filter>
</x-wirekit::reading-spine>
<x-wirekit::reading-minimap target="#docs-body" item-selector="h2, h3, h4" />
<x-wirekit::reading-bookmark
    key="docs-{{ $page->slug }}"
    :minDwellSeconds="120"
    :threshold="0.05"
/>
<x-wirekit::reading-meta :wpm="200" :showRemaining="true" />

<article id="docs-body">{{ $slot }}</article>

<div x-on:wirekit:reading-spine:section-changed.window="
    document.title = $event.detail.text + ' — Docs';
    /* analytics call: $event.detail.id, $event.detail.text */
">
    <x-wirekit::reading-shell ...>
        <article>...</article>
    </x-wirekit::reading-shell>
</div>