## 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](/getting-started/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:

```http
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:

```text
https://dashboard.ravi.id/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.id`. The CLI auth commands are `login`, `logout`, and `status` only.

```bash
ravi auth login
```

The API returns a verification URL at `https://api.ravi.id/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.

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.id` |
| `GET` | `/api/auth/device/callback/` | OAuth callback |

## Base URL

Use the production API host:

```text
https://api.ravi.id
```

Example:

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

## Next Steps

- [Sign Up](/getting-started/sign-up/)
- [Returning Login 2FA](/getting-started/returning-login-2fa/)
- [Credentials Across Worktrees](/getting-started/credentials-across-worktrees/)
- [API Overview](/api/overview/)
- [API Endpoints](/api/endpoints/)
- [Security Model](/security/security-model/)