How Reeve handles authentication — Clerk for users, session tokens for APIs, and service-to-service auth.

Authentication Overview

Reeve uses a layered authentication system. Users authenticate via Clerk, APIs use session tokens, and services communicate with shared secrets.

User Authentication

Users authenticate through Clerk with three options:

Method	How it works
Magic link	Enter your email → click the link in your inbox → signed in
Google OAuth	One-click sign-in with your Google account
Email + password	Traditional credentials

After authentication, Clerk issues a JWT. The frontend uses this JWT to request a session token from the Services API.

Session Tokens

For ongoing API access, Reeve issues session tokens — UUIDs stored in the database:

User → Clerk (magic link) → JWT → Services API → Session Token → All APIs

Session tokens are what the frontend, desktop app, and gateway use for all subsequent requests. They expire after 30 days of inactivity and can be revoked instantly.

Unlike JWTs, session tokens are opaque UUIDs — they don't carry claims and can be invalidated server-side without waiting for expiry.

Desktop App Authentication

The desktop app uses a device auth flow:

Desktop app opens a browser to the Clerk sign-in page
User authenticates via Clerk
Browser redirects back to the desktop app with an auth code
Desktop app exchanges the code for a session token
Token is stored locally for all API calls

The session token is refreshed automatically. You only need to sign in once.

Gateway Authentication

The local gateway uses a simpler model — a gateway token that secures the API:

{
  "gateway": {
    "auth": {
      "token": "your-secret-token"
    }
  }
}

When set, all requests to the gateway must include this token. The onboarding wizard generates one automatically.

Service-to-Service Auth

The gateway communicates with the Reeve Services API (cloud backend) using a shared secret:

Gateway → Services API
Header: X-Reeve-Services-Token: <shared-secret>

This token is set via the REEVE_SERVICES_TOKEN environment variable on both sides. It's never exposed to users or agents.

Auth Context

Every authenticated request provides user context:

Field	Description
`user_id`	Clerk user ID
`email`	User email address
`is_guest`	Whether this is a guest/demo session

Guest Mode

For unauthenticated demo access, a guest mode provides read-only access to demo data:

GET /api/dashboard
X-Guest-ID: guest_demo_123

No write operations are permitted in guest mode.

Cloud vs Local Auth

Feature	Cloud	Local (Desktop/CLI)
User sign-in	Clerk (magic link, Google, email)	Optional — connects to cloud account
API auth	Session tokens	Gateway token
LLM keys	Managed or BYOK	Always BYOK (your own keys)
Service comms	Service token (automatic)	Service token (if cloud-connected)

Security

All tokens are transmitted over HTTPS only
Session tokens are UUIDs — revocable instantly server-side
Clerk handles password hashing, rate limiting, and brute-force protection
Service-to-service tokens never leave server environments
CORS is configured for the frontend domain only
OAuth state tokens have a 10-minute TTL for CSRF protection

For LLM provider API keys (Anthropic, OpenAI, etc.), see API Keys. User authentication and LLM authentication are separate systems.

Authentication Overview

On this page