---
title: Authentication
summary: The apikey header, the domains a key may be called from, and what each refusal means.
description: How to authenticate against the World of Regions Platform API — the apikey header, domain restrictions, and every refusal explained.
order: 1
updated: "2026-09-14"
---

Every request carries an API key in a header. There is no OAuth flow, no token endpoint and
nothing to refresh: a key is a long-lived credential you create in the admin panel and keep on
your server.

## The apikey header

Send the key as `apikey`. The name `apitoken` is accepted as an alias for the same header, so an
integration written against the older name keeps working — but prefer `apikey` in new code.

```bash
curl -H "apikey: YOUR_KEY" \
  "https://world-of-regions.com/api/External/TravelInformationConfiguration?query=%7B%22language%22%3A%22EN%22%7D"
```

Keys are created in the admin panel under **API Configurator**, which is also where you switch
API access on for your organisation. A key is shown in full when it is created and can be copied
from that screen afterwards; treat it the way you would a password.

## Which domains a key may be called from

A key can be restricted to a list of domains — up to five. When that list is set, every request
must arrive with an `Origin` or a `Referer` naming one of them.

Two details decide whether this control does what you expect:

- **Only `Origin` and `Referer` are read.** The request's `Host` header is deliberately ignored,
  because `Host` is *our* hostname rather than the caller's — a request that sent neither of the
  other two would otherwise match the allow-list simply by omitting a header.
- **A request that carries neither is refused**, not waved through, whenever a key has a domain
  list. A caller with no verifiable origin cannot satisfy the list, and allowing it would make
  the list decorative.

Read the control for what it is. `Origin` and `Referer` are set by browsers and cannot be forged
by page JavaScript, so a domain list genuinely stops a third-party site embedding your key in
*their* front end. It is not protection against a stolen key used from a server, which can send
any header it likes. **A key with no domain list works from anywhere** — the right choice for a
server-to-server integration, and the wrong one for a key that ships to a browser.

## When a request is refused

| Status | Message | What it means |
|---|---|---|
| `401` | `Api key is invalid` | No key, an unknown key, or a domain-restricted key called from a domain that is not on its list. |
| `401` | `This API key is restricted to specific domains; the request carried no Origin or Referer` | The key has a domain list and the request gave nothing to match it against. |
| `402` | `Insufficient balance — top up to continue using the API` | The organisation's prepaid balance is spent. Top up in the panel and calls resume immediately. |
| `403` | `API access is disabled for this organisation` | The key is valid, but API access is switched off for the organisation that owns it. |

Every refusal is a JSON object with a single `message` field. Note that the two 401s are
different problems with the same status: read the message before assuming a key is wrong.

## Usage is recorded, and appears a few minutes later

Calls are counted per key and flushed every five minutes, so the first requests from a new
integration will not appear in the usage report the instant you make them. The count is what your
invoice is built from — see **Usage and billing**.