Auth Add-on

SAPIX_AUTH_ENABLED=true
SAPIX_AUTH_JWT_EXPIRY_SECS=3600          # optional — default 1 hour
SAPIX_AUTH_MAGIC_LINK_EXPIRY_SECS=900   # optional — default 15 min

// Register — creates a new user and returns a JWT
const res = await fetch("http://localhost:7475/v1/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "s3cr3t!" }),
});
const { user_id, email, token } = await res.json();

// Login — verify password, return JWT
const login = await fetch("http://localhost:7475/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "s3cr3t!" }),
});
const { token } = await login.json();

// All subsequent requests: attach the JWT
fetch("http://localhost:7475/v1/auth/me", {
  headers: { Authorization: `Bearer ${token}` },
});

import httpx

client = httpx.AsyncClient(base_url="http://localhost:7475")

# Register
r = await client.post("/v1/auth/register",
    json={"email": "user@example.com", "password": "s3cr3t!"})
token = r.json()["token"]

# Verify current user
me = await client.get("/v1/auth/me",
    headers={"Authorization": f"Bearer {token}"})
print(me.json())  # {"user_id": "usr_...", "email": "user@example.com"}

// Step 1: Request a magic link
// If SAPIX_MAIL_ENABLED=true → token is emailed automatically
// If mail not configured → token is returned in the response for testing
const req = await fetch("http://localhost:7475/v1/auth/magic-link/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com" }),
});
const { sent, token: testToken } = await req.json();
// sent: true  → email delivered  (token not shown)
// sent: false → token: "a3f9..."  (testing mode)

// Step 2: Verify the token from the link (single-use, deleted on verify)
const verify = await fetch("http://localhost:7475/v1/auth/magic-link/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: tokenFromEmail }),
});
const { token } = await verify.json(); // JWT

{
  "sub":          "usr_a3f9b2c1...",
  "email":        "user@example.com",
  "app_metadata": { "role": "parent", "family_id": "fam_9f2a" },
  "user_metadata":{ "display_name": "Alex" },
  "iat":          1749427200,
  "exp":          1749430800,
  "jti":          "3d8f2c1a..."
}

PATCH /v1/auth/users/user@example.com/app-metadata
Authorization: Bearer spx_root_YOUR_ROOT_KEY
Content-Type: application/json

{ "metadata": { "role": "parent", "family_id": "fam_9f2a" } }

// Response
{ "email": "user@example.com", "app_metadata": { "role": "parent", "family_id": "fam_9f2a" } }

PATCH /v1/auth/me/user-metadata
Authorization: Bearer <user_jwt>
Content-Type: application/json

{ "metadata": { "display_name": "Alex" } }

// Response
{ "email": "user@example.com", "user_metadata": { "display_name": "Alex" } }

SAPIX_OAUTH_GOOGLE_CLIENT_ID=<from Google Console>
SAPIX_OAUTH_GOOGLE_CLIENT_SECRET=<from Google Console>
SAPIX_OAUTH_GITHUB_CLIENT_ID=<from GitHub OAuth app>
SAPIX_OAUTH_GITHUB_CLIENT_SECRET=<from GitHub OAuth app>
SAPIX_OAUTH_REDIRECT_BASE_URL=https://<sapixdb-railway-url>
SAPIX_OAUTH_ALLOWED_REDIRECT_URIS=https://yourdomain.com,https://staging.yourdomain.com

// Your backend route: GET /oauth/google/callback?token=...&refresh_token=...
app.get('/oauth/google/callback', (req, res) => {
  const { token, refresh_token, email } = req.query;
  res.cookie('refresh_token', refresh_token, {
    httpOnly: true, secure: true, sameSite: 'lax', maxAge: 30 * 24 * 60 * 60 * 1000,
  });
  // Forward only the short-lived access token to the SPA
  res.redirect(`https://yourapp.com/?token=${encodeURIComponent(token)}`);
});

// Start the flow — redirect_uri points at YOUR backend, not the browser
const startUrl = `${SAPIX_URL}/v1/auth/oauth/google/authorize` +
  `?redirect_uri=https://api.yourapp.com/oauth/google/callback`;
window.location.href = startUrl;

// Add redirect_mode=fragment to the authorize URL
const startUrl = `${SAPIX_URL}/v1/auth/oauth/google/authorize` +
  `?redirect_uri=https://yourapp.com/callback&redirect_mode=fragment`;
window.location.href = startUrl;

// In your /callback page:
const hash = new URLSearchParams(window.location.hash.slice(1));
const token = hash.get('token');
const refreshToken = hash.get('refresh_token');

SAPIX_WEBAUTHN_RP_ID=yourdomain.com         # effective domain of the frontend (no scheme, no port)
SAPIX_WEBAUTHN_RP_NAME="Your App"           # display name shown in browser passkey prompt
SAPIX_WEBAUTHN_ORIGIN=https://yourdomain.com  # full HTTPS origin of the frontend

// 1. Get a challenge (requires the user's auth JWT from a prior login/magic-link)
const { session_token, creation_options } = await fetch('/v1/auth/passkey/register-challenge', {
  method: 'POST',
  headers: { Authorization: `Bearer ${userJwt}` },
}).then(r => r.json());

// 2. Ask the browser to create a passkey
const credential = await navigator.credentials.create({ publicKey: creation_options });

// 3. Register the passkey
await fetch('/v1/auth/passkey/register', {
  method: 'POST',
  headers: { Authorization: `Bearer ${userJwt}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ session_token, registration: credential }),
});
// → { "verified": true }

// 1. Get a challenge (email identifies which passkeys to use)
const { session_token, request_options } = await fetch('/v1/auth/passkey/authenticate-challenge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' }),
}).then(r => r.json());

// 2. Prompt the authenticator
const assertion = await navigator.credentials.get({ publicKey: request_options });

// 3. Authenticate
const { token, refresh_token } = await fetch('/v1/auth/passkey/authenticate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ session_token, assertion }),
}).then(r => r.json());
// Store token in httpOnly cookie — same as magic-link verify

curl -X POST http://localhost:7475/v1/organisms/acme/auth/init \
  -H "Authorization: Bearer $ROOT_KEY"
// → 201 { "organism_id": "acme", "agent_id": "acme::auth", "created_at_ms": ... }