API authentication

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

Note that each project in your account can use a different authentication method, giving you flexibility across environments, services and integrations.

Choosing an authentication method

Method	Best for	Requires
API key + Domain	Browser and widget integrations	Registered domain and API key
API key + Secret	Server-to-server calls	API key and secret
OAuth 2.0 Bearer Token	Automated systems, CI/CD, strict security requirements, scoped access control	OAuth 2.0 client credentials. Business or Enterprise plan.

OAuth 2.0 is available on Business or Enterprise plans. Enable in the Keys section of the Portal.

When choosing an authentication method, consider where the request originates and what level of credential control you need. Never expose your secret in client-side code.

For automated systems or where you need to limit credential scope to specific services, OAuth 2.0 gives you more control. It supports scoped credentials, meaning you can limit a set of credentials to specific services: address, email or phone.

Base endpoint

All requests are authenticated against:

https://api.addressfinder.io

See individual API pages for full endpoint paths.

API key + Secret

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. Never expose this in client-side code, version control or logs.

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 originates from a registered domain.

OAuth 2.0 Bearer Token

For machine-to-machine integrations, Addressfinder supports the OAuth 2.0 client credentials grant, following the industry-standard RFC 6749 flow. Tokens can be scoped to limit access to specific services: address, email or phone.

See the OAuth 2.0 Client Credentials guide for full details.

Using a Bearer token

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

OAuth 2.0 authentication does not require the key or secret parameters. The Bearer token carries all the information needed to identify your project and authorise the request.