Ravi is built for autonomous agents. An agent can onboard end to end by itself
and receive its API keys back programmatically. The only human step is a
one-time OAuth approval. There is no dashboard requirement.

A new account starts empty — **no identity is provisioned automatically.** After
signing up you use your management key to create the first identity, which
provisions its email inbox and free phone number at that moment.

## 1. Sign Up

Pick whichever path fits the runtime. All three create the same account and
yield the same keys.

### Over the API (device authorization grant)

The agent-native path. Uses the OAuth 2.0 Device Authorization Grant (RFC 8628):
the agent starts the flow, hands its human one link to approve, and polls for
the result.

```bash
# 1. Start the flow.
curl -X POST https://api.ravi.app/api/auth/device/
# → { "device_code": "...", "user_code": "ABCD-1234",
#     "verification_uri": "https://api.ravi.app/api/auth/device/verify/",
#     "expires_in": 600, "interval": 5 }
```

Hand your human the `verification_uri` and `user_code` from that response. They
open the link and approve with Google. **First-time approval creates the
account automatically.**

```bash
# 2. Poll for the result. `wait` long-polls up to 120s.
curl -X POST https://api.ravi.app/api/auth/device/token/ \
  -H "Content-Type: application/json" \
  -d '{"device_code": "...", "wait": true}'
# Pending: { "error": "authorization_pending" }
# Success: { "access": "...", "refresh": "...",
#            "management_key": "ravi_mgmt_...", "user": {...} }
```

Store the `management_key` (`ravi_mgmt_...`) in your secret manager. It is
long-lived and revocable. That is all you need to continue.

### With the CLI

`ravi auth login` runs the same device flow and opens the browser for you.

```bash
ravi auth login
```

See [Installation](/getting-started/installation/) to get the CLI.

### In the dashboard (human)

A human can sign in with Google at `https://dashboard.ravi.app/dashboard/login/` and
create keys at `https://dashboard.ravi.app/dashboard/api-keys/`.

## 2. Create Your First Identity

An **identity** is the persona your agent operates as — it owns an email inbox,
a phone number, contacts, and credentials. Create one with the management key.
This is where first value happens: the inbox and free phone are provisioned now.

```bash
export RAVI_MGMT_KEY="ravi_mgmt_..."

curl -X POST https://api.ravi.app/api/identities/ \
  -H "Authorization: Bearer $RAVI_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "research-agent",
        "email_identifier": "research",
        "provision_phone": true
      }'
# → identity with uuid, email address, and phone number
```

| Field | Meaning |
| --- | --- |
| `name` | Label for the identity (required) |
| `email_identifier` | Email local part; omit to auto-generate |
| `provision_phone` | Also provision a phone number |

With the CLI:

```bash
ravi identity create --name "research-agent"
ravi identity use <identity-uuid>
```

## 3. Scope a Runtime With an Identity Key (recommended)

For an autonomous agent, prefer an **identity-scoped key** (`ravi_id_...`):
losing one key does not expose the whole account. Mint one from the management
key:

```bash
curl -X POST https://api.ravi.app/api/auth/keys/identity/ \
  -H "Authorization: Bearer $RAVI_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity": "<identity-uuid>", "label": "research-runtime"}'
# → the full ravi_id_... key, shown once
```

| Key prefix | Scope | Use |
| --- | --- | --- |
| `ravi_mgmt_...` | Account + all identities | Create identities, mint identity keys, manage the account |
| `ravi_id_...` | One identity | Give an agent runtime access to exactly one identity |

The key is an **auth fence** — it defines what you may touch; the caller chooses
the identity. A management key targets an identity with `?identity=<uuid>`; an
identity key is already fenced to its identity.

## 4. Use the Identity

```bash
export RAVI_API_KEY="ravi_id_..."      # or the management key
export IDENTITY_UUID="<identity-uuid>"

# Confirm who the key is.
curl https://api.ravi.app/api/health/whoami/ \
  -H "Authorization: Bearer $RAVI_API_KEY"

# Read the identity's email and SMS inboxes.
curl "https://api.ravi.app/api/email-inbox/?identity=$IDENTITY_UUID" \
  -H "Authorization: Bearer $RAVI_API_KEY"
curl "https://api.ravi.app/api/sms-inbox/?identity=$IDENTITY_UUID" \
  -H "Authorization: Bearer $RAVI_API_KEY"
```

With the CLI, on the active identity:

```bash
ravi get email      # the identity's email address
ravi get phone      # the identity's phone number
```

## Next Steps

- [Quickstart](/getting-started/quickstart/) — make a first authenticated request
- [Authentication](/getting-started/authentication/) — key types, device flow, JWT refresh
- [API Endpoints](/api/endpoints/) — the full route map
- [Email](/core-concepts/email/) and [Phone & SMS](/core-concepts/phone-and-sms/) — receive verification codes and act