Authentication

Direct API requests require Authorization: Bearer YOUR_KEY. There is no built-in default credential.

Local browser access

pnpm dev:local and pnpm preview:local generate a local gateway credential in .data/local-gateway.key. The Next.js server attaches it to same-origin browser requests only when SHADERWEAVE_LOCAL_MODE=1.

The local gateway checks loopback host and origin. Never expose local mode through a public tunnel. Outside local mode, the gateway forwards HTTP-only session cookies and explicit bearer authentication without adding credentials. Local workspace keys are rejected in hosted mode.

Customer sign-in

Use Google or GitHub to create a personal workspace. Both providers identify your account without requesting repository access. Sessions use HTTP-only cookies, Secure in hosted HTTPS mode, with same-site protection. Cookie-authenticated mutations also require the matching Origin header. A revoked or malformed bearer key never falls back to a session.

The sign-in and callback routes live under /v1/auth. GET /v1/auth-config lists configured providers and the current session, and GET /v1/me returns the authenticated workspace owner. OAuth callback destinations are restricted to APP_ORIGIN. Account and billing data are not publicly cached.

API keys

Sign in and create keys in Account or through the API. Keys belong to your workspace and share its credit balance. The API_KEYS environment variable is only for the explicit local workspace; it cannot authenticate a hosted customer.

POST /v1/keys
Authorization: Bearer YOUR_KEY
Content-Type: application/json

{"label":"CI renderer"}

The secret is returned once. GET /v1/keys returns labels, prefixes, dates and revocation status. DELETE /v1/keys/{id} immediately revokes a persisted key.

Public endpoints

Health, readiness, sign-in provider discovery, generator discovery, OpenAPI JSON and the API reference are public. All rendering routes, including recipe URLs, and all jobs, presets, usage, billing and keys routes require authentication. The Stripe webhook endpoint uses its own raw-body signature authentication.

Image tags cannot attach a bearer header. Use a same-origin authenticated gateway or fetch a render with the SDK and display a blob URL.

Origins and webhooks

Set ALLOWED_ORIGINS to an explicit comma-separated list of browser origins. Unknown origins receive 403 origin_denied. There is no wildcard credential access.

Webhooks require HTTPS and a hostname in WEBHOOK_ALLOWED_HOSTS. Delivery has a five-second timeout and does not follow redirects.

Errors

Missing, invalid or revoked credentials return 401 with an application/problem+json response. Key hashes and plaintext secrets are excluded from request logs.