Getting started · Authentication

Authentication

Send your API key in the `X-API-Key` header on every `/v1/*` request. Only `GET /v1/health` needs no key.

D-201One host, two doors

How to authenticate

Create a key in the dashboard under API keys. One host serves both environments; the key decides which one a request runs in.

export NORBA_KEY="nbr_test_3f9c…"

curl --request POST \
  --url https://api.norba.io/v1/shopping/offers \
  --header "X-API-Key: $NORBA_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "origin": "LHR", "destination": "JFK", "departure_date": "2027-06-15", "adults": 1 }'

API key details

Property	Details
Acts as	The member who created it. If that member loses the permission a call needs, the key is refused with 403.
Format	nbr_test_ (sandbox) or nbr_live_ (production), then 32 hex characters. Treat it as opaque.
Production	Production keys can be created once your agency is approved to go live. A key only sees orders from its own environment.
Restrictions (optional)	IP allowlist (addresses or CIDR blocks) and endpoint allowlist (path prefixes such as /v1/shopping), up to 20 entries each; scopes; an expiry up to 2 years ahead. Changes apply at once.
Rotation	Rotate creates a new key and revokes the old one at once. Restrictions are not copied.
Sandbox	Reaches the airlines' test systems. Orders are test bookings, never real tickets.
Scopes	search.execute: /v1/shopping/* and /v1/offers/*. order.read: every GET under /v1/orders. order.create: POST /v1/orders. order.service: every other write on an order. A key with no scopes may call everything; other endpoints need no scope.
Viewing the secret	Shown once on creation. Reveal it later with your password or a fresh second factor.
Where to get it	Dashboard → API keys. Needs a verified email and, for a member who is not the owner, the permission to manage API keys.

Common auth errors

The body is `{ "error": "…" }`. 401: the key is not usable. 403: the key is valid but may not make this call.

HTTP	error	Meaning
401	api key has expired	Past its expiry date. Create a new key.
401	invalid api key	Unknown, revoked or deleted key, or a suspended agency.
401	missing X-API-Key	No header sent.
403	api key is not permitted from this address	Outside the key's IP allowlist.
403	api key is not permitted on this endpoint	Outside the key's endpoint allowlist.
403	api key lacks the <scope> scope	The key's scopes do not cover this call.
403	the account behind this api key … permission …	The key's creator lacks a permission this call needs. Ask an owner or admin.
403	the agency behind this api key is suspended	Contact support.
429	too many requests without a valid API key from this address …	Too many invalid keys from one address. Fix the key; retry after Retry-After.
503	could not verify the api key's restrictions, retry shortly	Nothing ran. Retry.

Billing refusals (402) and every other code: Errors & rate limits.