# auth.md

Crawlora supports agent access through the same OAuth sign-in and API-key flow used by the Crawlora console.

## Discovery

- Protected Resource Metadata: http://fe.tonywang.io/.well-known/oauth-protected-resource
- OAuth Authorization Server Metadata: http://fe.tonywang.io/.well-known/oauth-authorization-server
- OpenID-compatible metadata alias: http://fe.tonywang.io/.well-known/openid-configuration
- API resource: https://api.crawlora.net/api/v1
- OpenAPI document: https://api.crawlora.net/swagger/doc.json

## Register

Crawlora's agent registration metadata uses `identity_assertion` with a `verified_email` assertion and issues an `api_key` credential. The current registration ceremony sends the user through one of Crawlora's existing OAuth sign-in starts:

- Google: http://fe.tonywang.io/api/oauth/google/start?next=%2Fapp%2Fapi-keys
- GitHub: http://fe.tonywang.io/api/oauth/github/start?next=%2Fapp%2Fapi-keys

The OAuth callback signs the user into Crawlora, links or creates the Crawlora account through the existing backend OAuth route, and takes the user to API-key management.

Metadata fields:

- `register_uri`: http://fe.tonywang.io/api/oauth/google/start?next=%2Fapp%2Fapi-keys
- `claim_uri`: http://fe.tonywang.io/app/api-keys
- `identity_types_supported`: `identity_assertion`, `oauth_provider`
- `identity_assertion.assertion_types_supported`: `verified_email`
- `identity_assertion.credential_types_supported`: `api_key`

## Device Claim (recommended — receive the key programmatically)

The Register flow above signs the human in but ends with the API key sitting on http://fe.tonywang.io/app/api-keys — a human has to copy it back to you. If you'd rather receive it directly, use the RFC 8628 device authorization grant instead:

1. `POST http://fe.tonywang.io/oauth2/device-authorization` with `{"login_hint": "<the user's email, optional>"}`. Response: `{device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval}` — `verification_uri` is http://fe.tonywang.io/device.
2. Tell the user to open `verification_uri_complete` (or http://fe.tonywang.io/device and type in `user_code`) in their browser. If they don't already have a Crawlora account, this same page carries them through the same Google/GitHub sign-in as Register above — no separate signup step.
3. Poll `POST http://fe.tonywang.io/oauth2/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device_code>`, honoring `interval`. While waiting: `{"error": "authorization_pending"}`. Polling faster than `interval`: `{"error": "slow_down"}`. Expired or already used: `{"error": "expired_token"}`.
4. On success: `{"access_token": "<your Crawlora API key>", "token_type": "Bearer", "expires_in": 0, "scope": "crawlora.api"}`. `expires_in: 0` means non-expiring — the same key visible at http://fe.tonywang.io/app/api-keys, not a separate short-lived token.

This hands over the account's existing API key (Crawlora is one active key per account, not a separate key per integration) — it does not create a new key, and approving a device claim never reveals the key to anyone who isn't already signed in as that account.

## Credential

Crawlora REST API calls use an API key, not a third-party bearer token. After OAuth sign-in, use the user-authorized Crawlora API key as:

```http
x-api-key: $CRAWLORA_API_KEY
```

The credential scope is `crawlora.api`, covering documented Crawlora REST endpoints available to the user's account and plan.

For Crawlora MCP only, the same API key can also be sent to `https://mcp.crawlora.net/mcp` as:

```http
Authorization: Bearer $CRAWLORA_API_KEY
```

MCP continues to accept `x-api-key` for clients that support custom headers but not bearer token configuration.

## Call The API

Use the OpenAPI document and endpoint catalog to choose a supported endpoint, then send requests to https://api.crawlora.net/api/v1 with the `x-api-key` header.

## Notes For Agents

- Keep API keys out of browser code and model-visible logs.
- Do not use the Crawlora session JWT as a third-party bearer credential. The session token is an internal console session.
- Rotate or revoke API keys from http://fe.tonywang.io/app/api-keys.
- If an endpoint returns `401` or `403`, ask the user to confirm the selected API key, account plan, and billing status.