Every request to the mapping.travel API must include a valid API key in the X-API-Key header. You obtain this key from your mapping.travel account dashboard. Requests without a valid key are rejected with a 401 response before they reach any endpoint logic.
Get your API key
Sign in to your mapping.travel account at mapping.travel and navigate to Settings → API tokens. Generate a key for your organization. Copy it immediately: it is only shown once.
Treat your API key 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.
Include the key in requests
Pass your key in the X-API-Key header on every request:
Example
Replace <your-key> with your actual key value.
Authentication errors
401 Unauthorized
You receive a 401 response when the X-API-Key header is missing or the key is invalid (expired, malformed, or revoked).
If you see a 401, verify that:
- The
X-API-Key header is present and spelled correctly
- The key value is sent exactly as issued, with no extra whitespace or
Bearer prefix
- The key 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.
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.
Back off and retry after receiving a 429. Use exponential backoff to avoid hitting the limit repeatedly.
