# auth.md

Vehicle API issues sandbox API credentials to agents without a signup form.

**Audience:** AI agents and other autonomous clients that need a working credential without a human filling out a form or entering a card.

**Supported identity type:** `anonymous` (no identity assertion, no claim ceremony).

**Credential types issued:** `access_token` (OAuth Bearer) and `api_key` (the same secret, also accepted as `X-API-Key`).

## Discovery

1. Protected Resource Metadata: https://vehicles-api.com/.well-known/oauth-protected-resource
2. Authorization Server Metadata (includes the `agent_auth` block): https://vehicles-api.com/.well-known/oauth-authorization-server
3. Register at `agent_auth.register_uri`, then exchange the client credentials at `token_endpoint`

Unauthenticated API calls return `WWW-Authenticate: Bearer resource_metadata="https://vehicles-api.com/.well-known/oauth-protected-resource"`.

## Agent self-registration (anonymous)

**Registration endpoint (`register_uri`):** `POST https://vehicles-api.com/oauth/register`

### Step 1 — Register a client

```
curl -X POST https://vehicles-api.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "my-agent", "contact_email": "you@example.com"}'
```

Response (`201`): `{ "client_id": "...", "client_secret": "vdac_...", "token_endpoint": "https://vehicles-api.com/oauth/token", ... }`

### Step 2 — Exchange the client credentials for an access token

```
curl -X POST https://vehicles-api.com/oauth/token \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
```

Response (`200`): `{ "access_token": "key_...", "token_type": "Bearer", "expires_in": 604800, "scope": "api" }`

### Step 3 — Call the API

```
curl -X POST https://vehicles-api.com/api/v1/vin/report \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vin": "1HGCM82633A004352"}'
```

Or connect an MCP client to `https://vehicles-api.com/mcp` (Streamable HTTP) with the same Bearer token.

**Sandbox limits — not a production credential:**

- Fixed quota: 100 requests/month
- Fixed rate limit: 5 requests/minute
- The account expires 7 days after registration; `/oauth/token` stops issuing tokens after that
- `contact_email` is not verified — it is only used for abuse contact
- For production use, sign up as a human (below)

## Human signup (production access)

1. Create an account: https://vehicles-api.com/register
2. Start a plan from the dashboard (7-day free trial)
3. Copy your API key from https://vehicles-api.com/dashboard
4. Send it on every request as `X-API-Key: <key>` (or `Authorization: Bearer <key>`)

## Base URL

```
https://vehicles-api.com/api/v1
```

## Notes

- Keys are scoped to one account and its rate limit / monthly quota.
- A compromised human-issued key can be revoked and replaced from the dashboard.
- Full reference: https://vehicles-api.com/docs · LLM summary: https://vehicles-api.com/llms.txt
- Terms: https://vehicles-api.com/terms · Privacy: https://vehicles-api.com/privacy