# IsItAGoodCar authentication for agents

This document describes the authentication that is actually available to agents and automated clients. It is the authoritative auth guide referenced by llms.txt.

## Public, anonymous access

The vehicle read endpoints and MCP tools are public and do not require registration:

- `GET https://api.isitagoodcar.com/api/v1/vehicles/{registration}/`
- `GET https://api.isitagoodcar.com/api/v1/vehicles/{registration}/mot/`
- `GET https://api.isitagoodcar.com/api/v1/vehicles/{registration}/provenance/`
- `GET https://api.isitagoodcar.com/api/v1/vehicles/lookup/{registration}/` (legacy, richer payload)
- `GET https://api.isitagoodcar.com/api/v1/health/`
- `POST https://api.isitagoodcar.com/api/v1/mcp` (read-only MCP tools)

Anonymous rate limits are 60 requests per minute per IP for the vehicle REST endpoints and 120 JSON-RPC messages per minute per IP for MCP. Throttled responses use HTTP 429 and include `Retry-After`.

## Optional token authentication

Accounts can obtain a Django REST Framework auth token for account-scoped features (saved favourites, search history, personalised account state):

1. `POST https://api.isitagoodcar.com/api/v1/auth/request-login/` with `{"email": "you@example.com"}`.
2. Read the one-time code sent to that email.
3. `POST https://api.isitagoodcar.com/api/v1/auth/verify-code/` with `{"email": "you@example.com", "code": "123456"}`.
4. The response includes `token`. Send it on subsequent requests as:

```http
Authorization: Token YOUR_TOKEN
```

The scheme is `Token`, not `Bearer`. A token identifies an existing account; it does not purchase or unlock a report, bypass rate limits or grant access to another user's data. Provenance returns `completed` only where that account already unlocked the report. Do not send payment details to this API; agents cannot start a purchase or an extended-check payment.

## Not supported

OAuth 2.0, OpenID Connect, dynamic client registration and bearer-token discovery are not currently available. The former `/.well-known/oauth-*`, `/.well-known/openid-configuration` and `/.well-known/jwks.json` placeholders have been removed. Do not attempt those flows.

Browser-based clients should call the API from a server-side integration because cross-origin access is restricted to IsItAGoodCar's own domains.

## Discovery

- OpenAPI: https://isitagoodcar.com/openapi.json
- API catalog: https://isitagoodcar.com/.well-known/api-catalog
- MCP server card: https://isitagoodcar.com/.well-known/mcp/server-card.json
- Agent skill: https://isitagoodcar.com/.well-known/agent-skills/vehicle-lookup.md
- Developer guide: https://isitagoodcar.com/developers