API Authentication

Addressfinder supports multiple methods of authenticating API requests. Choose the method that best fits your use case.

Choosing an Authentication Method

Method	Best for	Requires
API Key + Domain	Browser/widget integrations	Registered domain
API Key + Secret	Simple server-to-server calls	API key and secret
OAuth2 Bearer Token	Automated systems, CI/CD, third-party integrations	OAuth2 client credentials

API Key & Secret

The simplest way to authenticate. Every project in the Addressfinder Portal has an API key and secret.

API Key (key parameter) — identifies your project. Safe to use in client-side code.
API Secret (Authorization header) — authenticates server-to-server requests.

Secret in the Authorization header
curl -H "Authorization: YOUR_API_SECRET" \
  "https://api.addressfinder.io/api/nz/address/autocomplete/?key=YOUR_API_KEY&q=184+will&format=json"

For browser-based requests, register your domain in the Portal instead of using the secret. The API key alone is sufficient when the request comes from a registered domain.

OAuth2 Client Credentials (Bearer Token)

For machine-to-machine integrations, Addressfinder supports the OAuth2 client credentials grant. This follows the industry-standard RFC 6749 flow.

Using a Bearer token
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://api.addressfinder.io/api/nz/address/autocomplete/?q=184+will&format=json"

OAuth2 authentication does not require the key or secret parameters. The Bearer token contains all the information needed to identify your project and authorize the request.