Authentication

Overview

Ravi supports two practical authentication paths:

1. API-key auth for programmatic callers and agent runtimes.
2. Device-code login for the CLI and local setup.

API keys are the better default for backend services and agent runtimes. Device-code login is useful for CLI and local user setup. See Sign Up for the agent-native device flow.

API Key Types

Key prefix	Scope	Use
ravi_mgmt_...	Account management	Managing resources for a user/account
ravi_id_...	One identity	Agent runtime operations scoped to one identity

Pass either key as a bearer token:

Authorization: Bearer ravi_id_...

Identity-scoped keys should be preferred for autonomous agents because losing one key does not expose the whole account. The key is an auth fence only — in the SDKs, the caller chooses an identity and works on its identity.email and identity.phone channels, which send ?identity=<uuid> on every request.

Creating API Keys

The simplest path is the dashboard:

https://dashboard.ravi.app/dashboard/api-keys/

You can also manage keys through authenticated backend routes:

Method	Endpoint
GET / POST	/api/auth/keys/management/
GET / DELETE	/api/auth/keys/management/<id>/
GET / POST	/api/auth/keys/identity/
GET / DELETE	/api/auth/keys/identity/<id>/

Key create responses reveal the full key once. Store it immediately in your secret manager.

Device-Code Login

ravi auth login runs the OAuth 2.0 Device Authorization Grant (RFC 8628) against https://api.ravi.app. The CLI auth commands are login, logout, and status only.

ravi auth login

The API returns a verification URL at https://api.ravi.app/api/auth/device/verify/. A public front door may be https://ravi.id/device. Do not open https://ravi.app/api/auth/device/verify/.

On success the CLI stores long-lived ravi_mgmt_... / ravi_id_... keys in ~/.ravi/config.json.

The CLI is one identity per machine. Shared ~/.ravi/config.json is not a multi-agent runtime. Do not run many agents by switching the CLI identity. Multiple agents on one host must use the HTTP API with per-identity ravi_id_... keys (or the Cursor Connect plugin).

The backend routes behind that flow are:

Method	Endpoint	Description
POST	/api/auth/device/	Create a device code
POST	/api/auth/device/token/	Poll for completion
GET / POST	/api/auth/device/verify/	Browser verification on api.ravi.app
GET	/api/auth/device/callback/	OAuth callback

Base URL

Use the production API host:

https://api.ravi.app

Example:

curl https://api.ravi.app/api/health/whoami/ \
  -H "Authorization: Bearer ravi_mgmt_..."

Next Steps

• Sign Up
• Returning Login 2FA
• Credentials Across Worktrees
• API Overview
• API Endpoints
• Security Model