Ravi

Sign Up

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.

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

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

ravi auth login

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

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
FieldMeaning
nameLabel for the identity (required)
email_identifierEmail local part; omit to auto-generate
provision_phoneAlso provision a phone number

With the CLI:

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

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:

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 prefixScopeUse
ravi_mgmt_...Account + all identitiesCreate identities, mint identity keys, manage the account
ravi_id_...One identityGive 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

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:

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

Next Steps