Skip to content
Ubhub Location Service
Authentication

Overview

Authentication

Every /v1 request is authenticated with an API key sent as a bearer token.

API keys

Keys are created in the dashboard. Each key belongs to your account, has its own name, rate limit and usage history, and looks like this:

Key format
geo_4f9KcX2mQ7rT1vZ8bN3pL6wY0sH5dJ2a
  • geo_ followed by 32 random letters and digits. There is one kind of key; keys created earlier with a geo_live_ or geo_test_ prefix keep working.
  • When you create a key you choose which endpoints it can call (geocoding, reverse geocoding, routing) and when it expires: after 30, 60 or 90 days, after a year, on a date you pick, or never.
  • The full key is shown once, when you create or regenerate it. The platform stores only a keyed hash, so nobody (including us) can show it to you again.
  • In the dashboard a key appears masked, for example geo_4f9K••••••••••••.

Sending your key

Send the key in the Authorization header using the Bearer scheme:

cURL
curl "https://developers.ubhub.mn/v1/geocode?q=Ulaanbaatar" \
  -H "Authorization: Bearer YOUR_API_KEY"

The header is the only accepted place. Keys in query strings are not supported, because URLs end up in logs, browser history and proxies.

Keeping keys safe

  • Treat keys like passwords. Store them in environment variables or a secret manager, never in source control.
  • Call the API from your server. Code that runs in a browser or a mobile app can be inspected, so a key inside it is public. Let your app call your backend, and let the backend add the key.
  • Use one key per application or environment, so you can revoke one without affecting the others.
  • If a key may have leaked, regenerate or revoke it immediately.

How this website does it

The public map calls a small server-side proxy on this site, which adds the site's own key before forwarding to /v1. The key never reaches the browser.

Managing keys

Key actions
ActionEffect
CreateIssues a new key for the endpoints you choose, with an expiry date or none, and shows the secret once. An account can have up to 25 active keys.
RenameChanges the label only. The secret keeps working.
RegenerateIssues a new secret for the same key. The old secret stops working immediately; the name, endpoints, expiry date and usage history are kept. Expired keys cannot be regenerated; create a new key instead.
RevokePermanently disables the key. Requests with it get 403 API_KEY_REVOKED. This cannot be undone.

Playground tokens

The API reference playground lets you send real requests from the browser with one of your keys. Because secrets are never stored, the site cannot use the key itself. Instead it asks for a short-lived token (geo_pt_…, valid 15 minutes) bound to the key you selected. Requests made with it count against that key's rate limit and appear in its usage. Playground tokens stop working as soon as the key is revoked.

Authentication errors

Authentication errors
StatusCodeWhen
401INVALID_API_KEYThe header is missing, malformed, or the key does not exist.
401INVALID_API_KEYThe key has expired (details.reason is "expired").
403API_KEY_REVOKEDThe key was revoked.
403ENDPOINT_NOT_ALLOWEDThe key is not allowed to call this endpoint (details.allowed_endpoints lists the ones it can call).
401 Unauthorized
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing API key. Send it in the Authorization header: 'Authorization: Bearer YOUR_API_KEY'."
  }
}