Authentication

Raven accepts three kinds of credentials. All are sent as Authorization: Bearer <token>. For an API key, X-Subscription-Token: <key> also works.

API keys

An account can have up to 10 keys. Only a hash of each key is stored, so a key is shown once, when it's created. Keys have the read and write scopes. Revoke a key in the dashboard. A tool holding a key can also revoke it itself, with POST /oauth/revoke token=<key>.

Never put a key in code or a commit. Keep it in a gitignored .env as RAVEN_API_KEY, in your OS keychain (the CLI does this), or in your agent's secret store.

Device flow

The device flow (RFC 8628) is how a CLI or coding agent signs a user up or in. The user clicks one link in a browser, and the agent receives an API key. A new account gets the free credit.

curl -s -X POST https://api.ravenoutreach.com/oauth/device/code \
  -d client_id=my-agent -d "client_name=My agent on $(hostname -s)"

{"device_code": "rvn_dc_…", "user_code": "WDJB-MJHT",
 "verification_uri": "https://ravenoutreach.com/activate",
 "verification_uri_complete": "https://ravenoutreach.com/activate?code=WDJB-MJHT",
 "expires_in": 900, "interval": 5}

Show the user verification_uri_complete and the user_code. The approval page shows the same code, so they can check it matches. Then poll the token endpoint every interval seconds:

curl -s -X POST https://api.ravenoutreach.com/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=rvn_dc_… -d client_id=my-agent

OAuth for MCP clients

MCP clients that support MCP authorization need only Raven's MCP URL. The flow:

1. The client calls https://api.ravenoutreach.com/mcp without a token and gets a 401. Its WWW-Authenticate header points to the resource metadata.
2. The client registers itself and sends the user to a consent page.
3. The user approves with one click. If they're new, they sign up first.