Get started

# Authentication

Create an API key in the [dashboard](https://opengeocoding.com/dashboard). The full key is shown only once. Store a secret key in your server’s environment, not in source control or browser code. For web pages, use a [browser key](#browser-keys) restricted to your origins.

## Send the key in a header

All six endpoints accept `x-api-key`. POST requests also need `Content-Type: application/json`.

Request headers 

```
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

You can instead use a Bearer token with the same key:

Alternative authentication 

```
Authorization: Bearer YOUR_API_KEY
```

Do not send both headers. If both are present, `x-api-key` takes precedence.

## Keep secret keys private

Never include a secret key in public bundles or apps. In web pages, use a browser key restricted to your origins; proxy mobile app requests through your server. Production requests must use HTTPS.

Revoke a compromised key in the dashboard and create a replacement. Revocation takes effect within the next key sync, normally 5 seconds.

Keys are accepted only in headers, including for GET requests. A key in the URL is ignored, so the request fails with `401`.

## Browser keys

Libraries such as MapLibre GL Geocoder and leaflet-control-geocoder call the API directly from the page. Give them a browser key: in the dashboard, choose **Browser key** and list the origins of your site, one per line. An origin is `https://host` with an optional port, without a path. `https://*.example.com` covers every subdomain of example.com, but not example.com itself. Plain HTTP is only allowed for `http://localhost` and `http://127.0.0.1`, on any port. A key can have up to 20 origins, and you can edit them later.

A browser key only works when the request’s `Origin` header matches one of its origins, and only over JSON, not gRPC. Otherwise the API returns `403` (`permission_denied`). Matching replies carry `Access-Control-Allow-Origin`, so the browser lets your page read them. Secret keys still work from a page but get no CORS headers, so browsers block their replies.

Autocomplete from the browser 

```
// In your page, with a browser key restricted to this site's origin.
const response = await fetch('https://api.opengeocoding.com/v1/autocomplete', {
  method: 'POST',
  headers: {
    'x-api-key': 'og_YOUR_BROWSER_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: input.value, limit: 5 })
});
const { suggestions = [] } = await response.json();
```

A browser key is public: anyone can read it from your page, and clients outside a browser can send any `Origin` header. The origin list stops other websites from using it in their visitors’ browsers, not determined abuse. Every key shares your account’s per-second limit and credits, and there is no overage, so the worst case is that your account runs out of credits, never a surprise bill. Autocomplete spends no credits. If a browser key is abused, revoke it and create a new one.

## Authentication failures

A missing, invalid, expired or revoked key returns HTTP `401` with code `unauthenticated`. These requests do not spend credits.

Canonical page: https://opengeocoding.com/docs/authentication