The end-user API.

Fetch the specification

curl https://auth.tilldev.dev/openapi.json
# same document, versioned path:
curl https://auth.tilldev.dev/v1/openapi.json

Served with wildcard CORS like the OIDC discovery documents, so Swagger UI, Postman, and codegen tools can load it straight from the URL — no download step.

Conventions the whole surface shares

• App resolution. Send X-TillAuth-App: <app public id>. (The API also accepts a tau_pub_… publishable key in Authorization, or infers the app from a <slug>.tilldev.app host — but routes that carry a user token occupy the Authorization header, so send the header.)
• Realm strictness. Account routes verify the token was minted for this app. Cross-realm tokens get a plain 401.
• Non-enumeration. Email-accepting public routes (magic send, reset request, verify resend, signup on a taken email) answer success-shaped regardless of account existence, with padded timing. Practical consequence for /v1/signup: a new account always returns the full bundle including user.id — even when verification is still pending (email_verified: false) — so the one response without an id is the taken-email case, which returns a bare { ok: true }. If you are provisioning server-side and need an id for every address, don't drive it through this route; use the authenticated admin surface (import / SCIM), which returns the id and reports an existing account explicitly as conflict. The address's real owner gets an “you already have an account” email, so the human is never left at a dead end.
• Refusals carry their reason. 403 step_up_required means “prove a factor, then retry”; 409 floor refusals name what to set up before removing a credential. Both are written to be shown to the user — handling guide.
• Rate limits. 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Sign in, sign up

Magic links + email verification

Passwords, passkeys, TOTP

Account + sessions

What this spec deliberately excludes