Ravi

API Authentication

Authentication model

Ravi uses JWT (JSON Web Token) authentication. Tokens are obtained through the OAuth device-code flow and managed automatically by the CLI and plugins.

Device-code flow

The device-code flow is designed for CLI and headless environments where a browser redirect isn’t possible:

1. Client requests device code    → POST /api/auth/device/
2. User opens URL in any browser  → Displayed in terminal
3. User completes OAuth in browser
4. Client polls for token         → POST /api/auth/device/token/
5. Token returned, stored locally

This flow works on headless VMs, SSH sessions, and CI environments — the browser can be on a different machine.

Token lifecycle

TokenLifetimeStorage
Access token1 hour~/.ravi/auth.json
Refresh tokenLong-lived~/.ravi/auth.json

The CLI and plugins handle token refresh automatically:

  • Refresh happens 5 minutes before expiry
  • On a 401 response, the client refreshes and retries once
  • New tokens are saved to disk immediately

Identity scoping

API requests are scoped to a specific Identity using the X-Ravi-Identity header:

GET /api/email-inbox/
Authorization: Bearer <access-token>
X-Ravi-Identity: <identity-uuid>

The CLI and plugins set this header automatically based on the active Identity. There is no way to access data from a different Identity without explicitly switching.

Billing and subscription

API endpoints that require an active subscription return HTTP 402 Payment Required when the user lacks the required plan. This gives agents a machine-readable signal to prompt the user to upgrade.

{
  "detail": "Active subscription required.",
  "code": "subscription_required"
}

API endpoints

All API endpoints are prefixed with /api/. Key endpoint groups:

Path prefixPurpose
/api/auth/Authentication (login, token refresh, device code)
/api/identities/Identity CRUD
/api/email-inbox/Email threads
/api/email-messages/Individual email messages
/api/sms-inbox/SMS conversations
/api/messages/SMS messages
/api/passwords/E2E-encrypted password entries
/api/vault/E2E-encrypted key-value secrets
/api/encryption/Encryption metadata (salt, public key, verifier)
/api/events/stream/Server-Sent Events for real-time updates

See API Endpoints for the full reference.

Next steps