OAuth 2.0 API

Endpoints

The oauth2TokenUrl value is returned by the OAuth 2.0 connection details endpoint.

What Problem This Solves

Some organisations require standards-based API authentication for procurement, security, or governance reasons. OAuth 2.0 client credentials supports this by letting an approved backend service request a scoped access token, then use that token when calling Azupay REST APIs.

This keeps access controlled to the permissions Azupay has enabled for your client. It also avoids relying on long-lived bearer tokens, because your system can request a new token when the current token expires.

Prerequisites

Before you implement OAuth 2.0 client credentials, you need:

• your Azupay clientId
• confirmation from Azupay that OAuth 2.0 can be enabled for your client
• confirmation of the oauth2AllowedScopes your client is permitted to use

Default API Endpoint Access

The default OAuth 2.0 endpoint access set includes:

If you are unsure whether OAuth 2.0 can be enabled for your client, or if your integration needs access outside the default scopes for your client, raise a Jira Service Desk ticket here.

How To Implement It

1. Enable OAuth 2.0 and retrieve your connection details.

   Call POST {{ENDPOINT}}/client/{{clientId}}/oauth2 using your Azupay clientId. Confirm the oauth2AllowedScopes in the response match the scopes agreed for your integration.

2. Store the credentials securely.

   Add oauth2ClientId, oauth2ClientSecret, oauth2TokenUrl, oauth2GrantType, oauth2TtlInSecs, and oauth2AllowedScopes to your backend configuration. These values should be available only to the server-side component that calls Azupay.

3. Request a JWT access token.

   Send a POST request to oauth2TokenUrl using the oauth2GrantType value. Include only scopes listed in oauth2AllowedScopes.

4. Cache the token until it is close to expiry.

   The setup response includes oauth2TtlInSecs, and the token response includes expires_in. Your system should request a new token before the current token expires rather than treating the bearer token as a permanent credential.

5. Call the Azupay REST API with the bearer token.

   Add the token to the API request:

   HTTP

   Authorization: Bearer <access_token>

6. Request a new token when required.

   If the token expires or is rejected, request a new token and retry the API call where appropriate. If oauth2ClientSecret is lost or exposed, please contact Azupay.

Enabling OAuth 2.0 via API

Use your Azupay clientId to enable OAuth 2.0 for your client and retrieve your OAuth 2.0 connection details:

POST https://api-uat.azupay.com.au/v1/client/{{clientId}}/oauth2

A successful response includes the OAuth 2.0 credentials, token endpoint, grant type, token lifetime, and allowed scopes for your client.

{
  "oauth2ClientId": "3n8q9p1k2l4m5o6p7q8r9s0t1u",
  "oauth2ClientSecret": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
  "oauth2TokenUrl": "https://auth-uat.azupay.com.au/oauth2/token",
  "oauth2GrantType": "client_credentials",
  "oauth2TtlInSecs": 3600,
  "oauth2AllowedScopes": [
    "RestAPI/GET:balance",
    "RestAPI/GET:paymentInitiation"
  ]
}

Treat oauth2ClientSecret as a sensitive credential. Store it only in secure backend configuration or a secrets manager. Do not expose it in browser code, mobile apps, logs, support tickets, or shared documentation.

Request A JWT Access Token via API

The oauth2TokenUrl and oauth2AllowedScopes values come from the OAuth 2.0 connection details response. The following example shows the standard client credentials pattern using HTTP Basic authentication for the client credentials and a form-encoded request body.

curl --request POST 'https://auth-uat.azupay.com.au/oauth2/token' \
  --user '3n8q9p1k2l4m5o6p7q8r9s0t1u:abcdef1234567890abcdef1234567890abcdef1234567890abcdef12' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=RestAPI/GET:balance RestAPI/GET:paymentInitiation'

If Azupay provides a different credential placement requirement for your token endpoint, follow the setup details provided with your OAuth 2.0 credentials.

A successful token response includes the JWT access token, token type, and expiry period.

{
  "access_token": "eyJraWQiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use access_token as the bearer token when calling enabled Azupay REST APIs.

curl --request GET 'https://{azupay-api-host}/{api-path}' \
  --header 'Authorization: Bearer eyJraWQiOiJ...' \
  --header 'Accept: application/json'

The token only authorises actions within the permissions configured for your client. Requesting a token does not grant access to APIs or operations outside those permissions.

Enabling Oauth 2.0 via Dashboard

Oauth 2.0 can be enabled via the Dashboard for admin and tech admin users in the settings page.

Things To Keep In Mind

• Request only approved scopes.

  Only request scopes listed in oauth2AllowedScopes. Unsupported or unauthorised scopes can cause token requests or API calls to be rejected.

• Access tokens expire.

  Access tokens are short-lived. Cache them only until they are close to expiry, then request a new token.

• Keep the client secret server-side.

  oauth2ClientSecret must remain server-side. If it is exposed, it should be rotated rather than retrieved or reused.

• Use this flow for server-to-server access only.

  This flow does not authenticate individual users and should not be used for browser-based or delegated customer journeys.

• API keys remain supported.

  OAuth 2.0 is an additional authentication option for enabled clients. API-key-based authentication remains supported unless Azupay confirms a change for your integration.