## Overview

Ravi supports two practical authentication paths:

1. **JWT/session auth** through the dashboard, OAuth, and device-code flow.
2. **API-key auth** for programmatic callers.

API keys are the better default for backend services and agent runtimes. Device-code login is useful for CLI and local user setup.

## 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.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

The CLI can authenticate without a local callback server:

```bash
ravi auth login
```

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

## JWT Refresh

JWT-backed callers refresh through:

```http
POST /api/auth/token/refresh/
Content-Type: application/json

{"refresh": "<refresh-token>"}
```

## Base URL

Use the production API host:

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

Example:

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

## Next Steps

- [API Overview](/api/overview/)
- [API Endpoints](/api/endpoints/)
- [Security Model](/security/security-model/)