API reference

Authentication

Bearer API keys

The OpenAPI BearerAuth scheme requires an API key in the Authorization header. The documented key prefixes are bd_test_ and bd_live_. Do not put keys in URLs, browser code, logs or this explorer.

Request example

Production contract, illustrative only; this is not a verified live request. Supply your key through a server-side environment variable, not a committed value.

curl 'https://api.britdatum.com/v1/postcodes/TN37%206DJ' \
  -H "Authorization: Bearer ${BRITDATUM_API_KEY}"

Permission and failure handling

401 — authentication_required

A valid API key is required. Check the configured credential; do not repeatedly retry an unchanged credential.

403 — forbidden

The authenticated key lacks permission. Resolve permission with the project owner before retrying.

The postcode operation specifies BearerAuth with no OAuth scopes. That does not mean anonymous access or unrestricted project access.

Test keys are not the public preview

A prefix alone does not establish a working Test environment. This site's upstream preview accepts no API key and is not BritDatum Test mode. No persisted-data or authentication readiness is implied.

Reference: OpenAPI securitySchemes.BearerAuth and operation security. Continue to postcode lookup.