Authentication
All maps.guru API requests require authentication via an API key. This page covers how keys work, how to manage them, and security best practices.
API Key Format
All keys use the mapx_ prefix for easy identification:
mapx_a1b2c3d4e5f6g7h8i9j0...
Authentication Methods
Pass your API key using one of these methods:
Query Parameter (Recommended for Map Tiles)
curl "https://api.maps.guru/v1/geocode?q=Paris&key=mapx_your_key"
Authorization Header
curl -H "Authorization: Bearer mapx_your_key" \
"https://api.maps.guru/v1/geocode?q=Paris"
X-API-Key Header
curl -H "X-API-Key: mapx_your_key" \
"https://api.maps.guru/v1/geocode?q=Paris"
API Key Scopes
Each key can be configured with specific service scopes:
| Scope | Services | Description |
|---|---|---|
maps | Tile serving, style JSON | Vector and raster map tiles |
geocoding | Forward and reverse geocoding | Address to coordinates and back |
routing | Directions, isochrones | Route calculation and travel time |
By default, new keys have all scopes enabled.
Managing Keys
Create a New Key
- Navigate to Dashboard → API Keys
- Click Create New Key
- Enter a name and select scopes
- Copy the key — it's only shown once
Revoke a Key
Revoked keys stop working immediately. Go to Dashboard → API Keys and click the revoke button on any active key.
Tip
Create separate keys for different environments (development, staging, production) so you can revoke one without affecting others.
Security Best Practices
- Never commit keys to version control — Use environment variables instead
- Use server-side proxying — Don't expose keys in client-side JavaScript
- Rotate keys regularly — Create new keys and revoke old ones periodically
- Use minimal scopes — Only grant the scopes each key actually needs
- Monitor usage — Watch for unexpected spikes that might indicate key compromise