---
title: Authenticating to Carragent
description: How AI agents authenticate to Carragent. Reading the public API and MCP server needs no key; OAuth 2.0 client credentials are optional and only raise the rate limit.
canonical: https://carragent.com/auth.md
---

# Authenticating to Carragent

Carragent's agent surfaces are public and read-only, and they need no key, token or account:

- REST API: https://carragent.com/api/v1 (spec: https://carragent.com/openapi.json)
- MCP server: https://carragent.com/api/mcp (Streamable HTTP)
- NLWeb: https://carragent.com/ask

Send requests without an Authorization header. The limit is 60 requests a minute per IP; a 429 carries Retry-After.

The steps below are optional. They get an OAuth 2.0 token, which raises the limit to 300 requests a minute per client. A token reads the same public catalog, nothing more.

## Step 1: Discover

- Protected resource metadata (RFC 9728): https://carragent.com/.well-known/oauth-protected-resource. It names the authorization server and the scopes: agents:read, plans:read, search:read.
- Authorization server metadata (RFC 8414): https://carragent.com/.well-known/oauth-authorization-server, with the registration and token endpoints.
- A request with a bad or expired token gets a 401 whose `WWW-Authenticate: Bearer resource_metadata="..."` header points at the protected resource metadata. A request without a token is never refused for lacking one.

## Step 2: Pick a method

- No authentication: the default, enough to read everything.
- OAuth 2.0 client credentials (RFC 6749, section 4.4): for the higher limit.

Not offered: the auth.md `agent_auth` registration. There is no `identity_endpoint`, and no `anonymous`, `service_auth` or `identity_assertion` (ID-JAG, `urn:ietf:params:oauth:token-type:id-jag`) registration. No token acts for a user or reaches a business's data, so there is no user identity to assert.

## Step 3: Register

`POST https://carragent.com/api/oauth2/register` (RFC 7591) with `{"client_name": "my-agent"}`. The answer has `client_id` and `client_secret`. Send an `Idempotency-Key` header (a UUID): a retry with the same key returns the same client instead of a second one.

## Step 4: Claim

No claim ceremony: a client works as soon as it is registered, and no person has to approve it.

## Step 5: Exchange

`POST https://carragent.com/api/oauth2/token` with `grant_type=client_credentials` and the client's id and secret (HTTP Basic or form fields). Optional `scope`: agents:read plans:read search:read. The token lasts 60 minutes; get a new one the same way.

## Step 6: Use the access_token

Send `Authorization: Bearer <access_token>` to https://carragent.com/api/v1, https://carragent.com/api/mcp or https://carragent.com/ask.

## Errors

| Code | Where | What to do |
| --- | --- | --- |
| `invalid_request` (400) | register, token | The body or the Idempotency-Key is malformed. Fix it and retry. |
| `invalid_client_metadata` (400) | register | Send JSON metadata with the client_credentials grant and scopes from Step 1. |
| `unsupported_grant_type` (400) | token | Use `grant_type=client_credentials`. |
| `invalid_client` (401) | token | Wrong client id or secret. Check them, or register again. |
| `invalid_scope` (400) | token | Ask only for scopes the client registered with. |
| `invalid_token` (401) | API, MCP, NLWeb | Get a new token (Step 5), or call without Authorization. |
| `insufficient_scope` (403) | API, NLWeb | Get a token with the scope named in WWW-Authenticate. |
| `rate_limited` (429) | any | Wait the Retry-After seconds. |
| `temporarily_unavailable` (503) | register, token | OAuth is off for now. The API still answers without a token. |

## Revocation

There is no revocation endpoint: tokens are signed, stateless and expire after 60 minutes. To retire a client, stop asking for its tokens; a new client starts again at Step 3.

## Customer accounts

A business's own dashboard (https://carragent.com/dashboard) is for its owner and team only, behind email sign-in. Agents do not sign in on their behalf and there is no API to create or manage an account; send the user to https://carragent.com/en/pricing to start.

## Support

Email admin@carragent.com.