OAuth2 Client Credentials

The OAuth2 client credentials grant provides a standard way to authenticate machine-to-machine API calls. Instead of passing an API key and secret with every request, you exchange client credentials for a short-lived access token (JWT) and use that token to authorize API calls.

How it works

┌───────────┐                         ┌─────────────┐
│  Client   │──1. POST /oauth/token──▶│   API       │
│ (your app)│◀──2. Access Token───────│  Server     │
│           │──3. API call + Bearer──▶│             │
│           │◀──4. API response───────│             │
└───────────┘                         └─────────────┘

1. Your application requests an access token from the API server's token endpoint using your client credentials.
2. The API server validates your credentials and returns a signed JWT access token.
3. Your application includes the access token in the Authorization header of subsequent API requests.
4. The API verifies the token and returns the response.

OAuth2 client credentials must be enabled on your account before use. Contact us to request access.

Step 1: Create OAuth2 credentials

1. Log in to the Addressfinder Portal.
2. Navigate to your project's Credentials page. Contact us to enable this feature.
3. In the OAuth2 Client Credentials section, click Create OAuth2 Client ID and Secret.
4. Copy the Client Secret immediately — it is only displayed once and cannot be retrieved later.
5. Store the Client ID and Client Secret securely.

Keep your client secret confidential. Never expose it in client-side code, version control, or logs. The secret is only shown once at creation time.

Step 2: Request an access token

Exchange your client credentials for an access token by making a POST request to the token endpoint.

Endpoint: POST https://api.addressfinder.io/oauth/token

Parameters:

Parameter	Type	Required	Description
grant_type	string	Yes	Must be client_credentials
client_id	string	Yes	Your OAuth2 client ID
client_secret	string	Yes	Your OAuth2 client secret
scope	string	No	Space-separated list of requested scopes. Defaults to all scopes permitted by your client.
expires_in	integer	No	Requested token lifetime in seconds. Default: 900 (15 minutes). Maximum: 3600 (1 hour).

Available scopes:

Scope	Description
address	Access to address autocomplete, verification, and metadata APIs
phone	Access to phone verification API
email	Access to email verification API

Example request

curl -X POST https://api.addressfinder.io/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=address phone"

Example request with custom expiry

curl -X POST https://api.addressfinder.io/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=address" \
  -d "expires_in=3600"

Example response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "address phone"
}

Error responses

HTTP Status	Error	Description
400	unsupported_grant_type	The grant_type parameter is not client_credentials
400	invalid_scope	Requested scopes are invalid or not permitted for this client
401	invalid_client	Client credentials are incorrect or the client is disabled

Step 3: Call the API with the Bearer token

Include the access token in the Authorization header using the Bearer scheme.

Address autocomplete with Bearer token

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  "https://api.addressfinder.io/api/au/address/autocomplete/?q=274+Harb&source=GNAF,PAF&format=json"

Address verification with Bearer token

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  "https://api.addressfinder.io/api/au/address/v2/verification/?q=274+Harbour+Drive%2C+COFFS+HARBOUR+NSW+2450&format=json"

Phone verification with Bearer token

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  "https://api.addressfinder.io/api/phone/verification/?phone_number=0123456&country_code=AU&format=json"

When using a Bearer token, you do not need to include the key or secret parameters. The token carries all the authorization information.

Step 4: Handle token expiry

Access tokens expire after the duration specified in the expires_in field (default: 900 seconds / 15 minutes). Your application should:

1. Cache the access token and reuse it for multiple API calls.
2. Track the expires_in value from the token response.
3. Request a new token before the current one expires.

Example: Token refresh logic (pseudocode)

import time

token = None
token_expires_at = 0

def get_access_token():
    global token, token_expires_at

    # Refresh if token is missing or expires within 60 seconds
    if token is None or time.time() >= token_expires_at - 60:
        response = request_new_token()
        token = response["access_token"]
        token_expires_at = time.time() + response["expires_in"]

    return token

def call_api(query):
    access_token = get_access_token()
    response = requests.get(
        "https://api.addressfinder.io/api/nz/address/autocomplete/",
        params={"q": query, "format": "json"},
        headers={"Authorization": f"Bearer {access_token}"}
    )
    return response.json()

API error codes

When authentication fails at the API level, the response includes an error code:

Error Code	Message	Description
1024	Invalid or expired bearer token	The JWT is malformed, expired, has an invalid signature, or was issued by an untrusted source
1025	Project not found for bearer token	The token is valid but references a project that does not exist

These errors return HTTP status 400 with a JSON body:

{
  "completions": [],
  "message": "Invalid or expired bearer token",
  "error_code": "1024",
  "success": false
}

Security considerations

• Token lifetime: Access tokens are valid for up to 1 hour (default 15 minutes). Short-lived tokens limit the impact of token leakage.
• Transport security: Always use HTTPS when requesting tokens and calling the API.
• Credential storage: Store your client ID and secret in environment variables or a secrets manager — never in source code.
• Scope minimisation: Only request the scopes your application needs.
• Token caching: Cache tokens and reuse them; do not request a new token for every API call.

JWKS endpoint

The API server publishes its public signing keys at:

GET https://api.addressfinder.io/.well-known/jwks.json

This follows the JSON Web Key Set (JWKS) standard. If you need to verify tokens independently (e.g., in a reverse proxy), you can use this endpoint to retrieve the public keys.