OAuth 2.0 APIs

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 API endpoints or OAuth 2.0 scopes your client is permitted to use

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.

OAuth 2.0 scope access

The oauth2AllowedScopes value tells your system which OAuth 2.0 scopes it can request when getting a JWT access token.

Each scope maps to an API method and endpoint. For example, RestAPI/GET:balance allows a token to be requested for GET /balance.

Azupay confirms which scopes are available for your client during onboarding. If no client-specific scope set is required, Azupay applies the default endpoint access set. The oauth2AllowedScopes value in the response reflects the scopes available to your client.

Default API endpoint access

The default OAuth 2.0 endpoint access set includes:

Your oauth2AllowedScopes response confirms which API endpoints your client can request access to. If your integration needs access outside the scopes returned for your client, raise a Jira Service Desk ticket so Azupay can review your client permissions.

How to implement it

Follow this sequence from your backend system:

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 {{ENDPOINT}}/client/{{clientId}}/oauth2
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

{}

This request uses your existing API-key authentication. If your API key is HMAC-enabled, include the required HMAC signature for this request.

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/POST:paymentRequest",
    "RestAPI/POST:paymentRequest:refund",
    "RestAPI/POST:accountEnquiry",
    "RestAPI/POST:payIDEnquiry",
    "RestAPI/POST:payment",
    "RestAPI/GET:payment",
    "RestAPI/POST:payment:search",
    "RestAPI/GET:paymentRequest",
    "RestAPI/DELETE:paymentRequest",
    "RestAPI/POST:paymentRequest:search",
    "RestAPI/GET:report",
    "RestAPI/GET:report:download",
    "RestAPI/GET:balance"
  ]
}

The oauth2AllowedScopes array reflects the scopes available to your client. If no client-specific scope set is required, Azupay applies the default endpoint access set.

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.

oauth2ClientSecret is returned only once when OAuth 2.0 is enabled. Store it securely when you receive it. Subsequent requests to retrieve OAuth 2.0 connection details do not return the client secret.

Retrieve OAuth 2.0 connection details via API

After OAuth 2.0 has been enabled, use GET /v1/client/{{clientId}}/oauth2 to retrieve your OAuth 2.0 connection details.

GET {{ENDPOINT}}/client/{{clientId}}/oauth2
Authorization: SECR_MYBUSINESSID_myapikey

A successful response includes the OAuth 2.0 client ID, token endpoint, grant type, token lifetime, and allowed scopes. It does not include oauth2ClientSecret.

{
  "oauth2ClientId": "3n8q9p1k2l4m5o6p7q8r9s0t1u",
  "oauth2TokenUrl": "https://auth-uat.azupay.com.au/oauth2/token",
  "oauth2GrantType": "client_credentials",
  "oauth2TtlInSecs": 3600,
  "oauth2AllowedScopes": [
    "RestAPI/POST:paymentRequest",
    "RestAPI/POST:paymentRequest:refund",
    "RestAPI/POST:accountEnquiry",
    "RestAPI/POST:payIDEnquiry",
    "RestAPI/POST:payment",
    "RestAPI/GET:payment",
    "RestAPI/POST:payment:search",
    "RestAPI/GET:paymentRequest",
    "RestAPI/DELETE:paymentRequest",
    "RestAPI/POST:paymentRequest:search",
    "RestAPI/GET:report",
    "RestAPI/GET:report:download",
    "RestAPI/GET:balance"
  ]
}

Request a JWT access token via API

Use the oauth2TokenUrl, oauth2ClientId, and oauth2ClientSecret returned in the OAuth 2.0 connection details response to request a JWT access token. Do not use your Azupay clientId as the client_id in the token request.

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

Because this request does not pass a scope value, the issued token can include the default scopes available to your client.

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://api-uat.azupay.com.au/v1/balance' \
  --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.

Requesting a token with restricted scope

You can request a JWT access token for a subset of your oauth2AllowedScopes by passing only the scopes required for the API calls your system is about to make.

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

Only request scopes returned in oauth2AllowedScopes. Scopes outside your allowed list will not be included in the issued token.

Things to keep in mind