# OAuth or API key

The Data MCP server accepts two kinds of credentials. Both reach the same tools, scopes, limits and billing; they differ in who holds the secret and whether test mode is available.

## Compare

| | API key | OAuth |
| --- | --- | --- |
| How it is sent | `Authorization: Bearer au_test_...` or `au_live_...` | An access token the client gets by signing you in |
| Who sets it up | A developer creates a key in the console | The person using the client signs in and approves |
| Test mode | Yes, with a test key: free, simulated results | No. OAuth valuations are always **live** |
| Scopes | Chosen per key in the console | Requested by the client and approved on the consent page |
| Markets and spend limits | Per key, plus workspace limits | Workspace limits |
| Revocation | Revoke the key under **API keys** | Remove the member, or revoke the connection in the client |
| Best for | Servers, CI, scripts, development, evaluating agents | People using Claude, ChatGPT, Cursor and other assistants |

**Rule of thumb:** start every agent with a **test API key**. Move to OAuth (or a live key with a monthly credit limit) only when you have seen how the agent behaves.

## API keys

Create a key under **API keys** in the console ([authentication & keys](/docs/authentication)). For an agent:

- Use a **test key** while you set up and evaluate the agent.
- Give a live key only the scopes it needs. An agent that only looks up vehicles needs `catalogue:read` (and `account:read` for its setup check), not `valuations:write`.
- Set a **monthly credit limit** on live keys used by agents.
- Restrict the key to the markets the agent works in.
- Put the key in an environment variable or the client's secret input. Never paste it into a chat, a prompt or a shared config file.

The server treats any bearer token that starts with `au_` as an API key.

## OAuth

OAuth-capable clients discover everything themselves:

1. The client calls `https://data-services.autouncle.com/mcp` without a token and receives `401` with a `WWW-Authenticate` header pointing at `https://data-services.autouncle.com/.well-known/oauth-protected-resource/mcp`.
2. That metadata names the protected resource, `https://data-services.autouncle.com/mcp`, and AutoUncle's central sign-in as its authorization server.
3. The client registers itself (dynamic client registration) or uses a client ID you configured, then opens the sign-in page.
4. You sign in with your verified AutoUncle account, check the application and its callback address, **choose the organization** that should grant access and approve the scopes.
5. The client receives a token bound to the Data MCP resource and that organization.

Your membership and the token's scopes are checked again on every tool call, so removing a member or changing their role takes effect immediately. A token issued for another AutoUncle MCP server is not accepted here.

### Scopes

| Scope | Allows |
| --- | --- |
| `valuations:write` | `valuate_car` (spends credits when live) |
| `valuations:read` | `get_valuation` |
| `catalogue:read` | `search_vehicles` |
| `account:read` | `get_account` |

Approve only what the agent needs. A missing scope returns `insufficient_scope` for that tool.

### For client implementers

- Authorization code flow with PKCE (`S256`) and a random `state`.
- Use the authorization and token endpoints from the authorization server metadata.
- Send `resource=https://data-services.autouncle.com/mcp` exactly, in both the authorization request and the token exchange. Do not substitute another resource or organization when refreshing.
- The authorization server supports dynamic client registration, public clients (`none`) and `client_secret_basic` / `client_secret_post`. It does not advertise client ID metadata documents (CIMD); clients that prefer CIMD fall back to dynamic registration.
- Keep access and refresh tokens in secure storage.

## Which to choose

- **Building or testing an agent:** test API key.
- **Running an agent in your own backend:** live API key with narrow scopes, market restriction and a monthly credit limit.
- **Giving colleagues access in a chat assistant:** OAuth, so each person signs in as themselves and no key is shared.
- **ChatGPT:** OAuth only; ChatGPT cannot send an API key.

See [safety & spend control](/docs/mcp/safety) before you give an agent live access.