Authentication
Set your API key and base URL for HTTP or an SDK.
Send your primary API key in the apikey request header:
GET /v1/geocode?street=11%20Wall%20Street&city=New%20York HTTP/1.1
apikey: YOUR_API_KEY
Every request is checked against your API key and account rate limits. The SDK adds this header automatically using apiKey in TypeScript/PHP or api_key in Python. Do not put the key in the URL; keys in query strings are rejected and tend to leak into logs.
Base URL
Configure the origin or deployment prefix, such as http://localhost:8000 for local development. The SDK appends the operation path: /v1/geocode, /v1/search, /v1/reverse, /v1/autocomplete, or /v1/place. Do not include an endpoint path in the configured base URL.
SDK base URLs require HTTPS except for local development on localhost, localhost., 127.0.0.1, or IPv6 loopback [::1]. Embedded credentials, query strings, and fragments are rejected. Redirects are not followed.
Key management
Open API keys (/app/keys) in your deployment's account portal. Owners and admins can create and revoke credentials; other workspace members can view the list and key prefixes.
Owners and admins can invite teammates from Users management (/app/users). An email address can have one pending workspace invitation at a time. Resending from the same workspace refreshes its seven-day validity; another workspace must wait for it to expire or be consumed. Stripe Checkout and the billing portal return signed-in users to Billing details (/app/billing).
| Credential type | Prefix | Access | Store it in |
|---|---|---|---|
| Server API key | loc_ | All documented endpoints | Backend configuration or a secret store |
| Browser token | pub_ | Autocomplete and resolution from allowed origins | Your frontend's configuration |
Under Create a key, select the credential type and enter a Key name (up to 80 characters). For a browser token, also enter 1–20 Allowed domains or origins, one per line. Click Create API key or Create browser token, then use Copy key in the confirmation panel. The full value is shown only after creation; the active-key list shows a prefix.
To rotate a credential, create a replacement, update your application, and use Revoke next to the old key. Confirming revocation stops applications using that credential. To change a browser token's origins, replace the token rather than editing it.
The full geocoding SDKs are designed for backend use. For geocode, reverse geocode, or provider fallbacks from a browser or mobile frontend, call your own backend and let it invoke the SDK. For frontend autocomplete, use the dedicated browser client with a public token. Avoid returning server/provider credentials to clients or logging complete provider request URLs.
Backup provider credentials
Google and HERE fallbacks each require your own provider key. They are optional and use those providers' accounts and quotas. Configure only the providers you intend to call. Each backup call sends address or coordinate data directly to that provider.
An authentication or other HTTP 4xx error from the primary API stops the SDK provider chain. Backups do not bypass primary authentication failures. See errors and fallbacks.
Public browser tokens
Use the browser autocomplete client in any frontend library. Workspace admins create pub_ tokens with 1–20 exact allowed origins in the account portal. They work only on GET /v1/autocomplete and GET /v1/place, and require an allowed Origin plus the token in the apikey header. Missing or unlisted origins and other operations return HTTP 403. CORS preflight requests do not need credentials; authenticated requests still enforce the allow-list. Bare domains mean HTTPS; list each subdomain and development port separately. No wildcard domains are accepted.
Tokens are public and requests still count toward your rate limits and billing. Non-browser callers can forge Origin headers, so domain restrictions do not make tokens secret. Keep backend credentials on the server. Optional browser Google/HERE fallbacks use separate public, website-restricted provider keys configured in the SDK; they are sent directly to providers. No JSON request fields change.