> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate requests to the Mapping.Travel API

> Authenticate Mapping.Travel API requests with Bearer tokens. Get your token, set the Authorization header, and handle 401, 403, and 429 error responses.

Every request to the Mapping.Travel API must include a valid Bearer token in the `Authorization` header. You obtain this token from your Mapping.Travel account dashboard. Requests without a valid token are rejected with a `401` response before they reach any endpoint logic.

## Get your API token

Sign in to your Mapping.Travel account at [mapping.travel](https://mapping.travel) and navigate to **Settings → API tokens**. Generate a token for your organization. Copy it immediately—it is only shown once.

<Warning>
  Treat your API token like a password. Do not commit it to source control or expose it in client-side code. Use environment variables or a secrets manager to inject it at runtime.
</Warning>

## Include the token in requests

Pass your token as a Bearer token in the `Authorization` header on every request:

```
Authorization: Bearer <your-token>
```

### Example

```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/mapping \
  -H "Authorization: Bearer <your-token>"
```

Replace `<your-token>` with your actual token value.

## Authentication errors

### 401 Unauthorized

You receive a `401` response when the `Authorization` header is missing or the token is invalid (expired, malformed, or revoked).

```json theme={null} theme={null}
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```

If you see a `401`, verify that:

* The `Authorization` header is present and spelled correctly
* The token value starts with `Bearer ` (note the trailing space before the token)
* The token has not expired or been revoked in your dashboard

### 403 Forbidden

A `403` response means your token is valid but your account cannot perform the action. This typically occurs when your plan quota is exhausted.

```json theme={null} theme={null}
{
  "status": 403,
  "error": "Forbidden",
  "message": "Quota exceeded - upgrade to Paid plan for unlimited mappings"
}
```

Check your usage in the dashboard under **Billing → Usage**, or call `GET /api/v1/billing/usage` to inspect remaining quota programmatically.

## Rate limiting

The API enforces per-organization rate limits. When you exceed the limit, the API returns a `429 Too Many Requests` response.

```json theme={null} theme={null}
{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}
```

<Tip>
  Back off and retry after receiving a `429`. Use exponential backoff to avoid hitting the limit repeatedly.
</Tip>