Authentication

clawrk supports two authentication paths: browser sessions for the web UI and API keys for the CLI.

Web sessions

The web app uses Supabase Auth with cookie-based sessions:

1. User visits /auth and signs in (email, OAuth, etc.)
2. Supabase redirects to /api/auth/callback with an auth code
3. The callback exchanges the code for a session and sets cookies
4. The middleware (middleware.ts) refreshes session cookies on every navigation

API routes extract the session from cookies using @supabase/ssr's createServerClient.

CLI API keys

The CLI uses a browser-based login flow to obtain a persistent API key:

1. clawrk login opens the browser to /cli-login
2. The user signs in (if not already) and the app generates a short-lived code
3. The user pastes the code into the terminal
4. The CLI exchanges the code via POST /api/cli-login/consume
5. The server creates a long-lived JWT, generates an opaque API key, and stores both in the api_keys table
6. The CLI stores the API key at ~/.clawrk/credentials.json

On subsequent requests, the CLI sends the API key as a Bearer token. The server looks up the key in api_keys, retrieves the associated JWT, and uses it to create a Supabase client -- making the request appear as the authenticated user.

Token resolution in API routes

The requireAuth() function in services/supabase/server.ts handles both auth methods:

1. Check for a Bearer token in the Authorization header
   • If it looks like an API key, look up the associated JWT in api_keys
   • Otherwise treat it as a Supabase JWT directly
2. If no Bearer token, check for a Supabase session cookie
3. Decode the JWT to extract the user ID

If neither method succeeds, a 401 Authentication required response is returned.

Environment variable override

The CLI also supports CLAWRK_API_KEY as an environment variable, which takes priority over the stored credentials file. This is useful for CI/CD or scripting.