# 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: https://crawlora.net/.well-known/oauth-protected-resource
- OAuth Authorization Server Metadata: https://crawlora.net/.well-known/oauth-authorization-server
- OpenID-compatible metadata alias: https://crawlora.net/.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: https://crawlora.net/api/oauth/google/start?next=%2Fapp%2Fapi-keys
- GitHub: https://crawlora.net/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`: https://crawlora.net/api/oauth/google/start?next=%2Fapp%2Fapi-keys
- `claim_uri`: https://crawlora.net/app/api-keys
- `identity_types_supported`: `identity_assertion`, `oauth_provider`
- `identity_assertion.assertion_types_supported`: `verified_email`
- `identity_assertion.credential_types_supported`: `api_key`

## 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 https://crawlora.net/app/api-keys.
- If an endpoint returns `401` or `403`, ask the user to confirm the selected API key, account plan, and billing status.