openapi: 3.2.0 info: title: Azupay Configuration API Keys API description: API Reference version: v1 contact: email: contactus@azupay.com.au servers: - url: https://api-uat.azupay.com.au/v1 description: UAT environment - url: https://api.azupay.com.au/v1 description: Production environment tags: - name: API Keys description: 'Manage API keys for your clients. ' paths: /client/{clientId}/apiKeys: post: security: - SecretKey: [] tags: - API Keys summary: Create API keys for Sub Merchants description: Create API keys operationId: apiKeysProvision parameters: - name: clientId in: path required: true schema: $ref: '#/components/schemas/SubClientIdObj' requestBody: content: application/json: schema: $ref: '#/components/schemas/apiKeysProvisionObj' responses: '201': description: API key creation content: application/json: schema: allOf: - $ref: '#/components/schemas/apiKeysProvisionResponseObj' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '401': description: Invalid Authorization header content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny '404': description: Client ID not found content: application/json: schema: $ref: '#/components/schemas/ErrorModel' get: parameters: - name: clientId in: path required: true schema: $ref: '#/components/schemas/SubClientIdObj' security: - SecretKey: [] tags: - API Keys summary: Get API keys for Sub Merchants description: Get API keys operationId: getApiKeys responses: '200': description: API keys record content: application/json: schema: allOf: - $ref: '#/components/schemas/GetApiKeysResponseObj' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '401': description: Invalid Authorization header content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny '404': description: Client ID not found content: application/json: schema: $ref: '#/components/schemas/ErrorModel' /client/{clientId}/apiKeys/{apiKeyId}: get: parameters: - name: clientId in: path required: true schema: $ref: '#/components/schemas/SubClientIdObj' - name: apiKeyId in: path required: true schema: $ref: '#/components/schemas/ApiKeyIdObj' security: - SecretKey: [] tags: - API Keys summary: Gets an API key based on the API key ID. description: Get API key operationId: getApiKey responses: '200': description: API key record content: application/json: schema: allOf: - $ref: '#/components/schemas/GetApiKeyResponseObj' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '401': description: Invalid Authorization header content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny '404': description: Client ID not found content: application/json: schema: $ref: '#/components/schemas/ErrorModel' patch: security: - SecretKey: [] tags: - API Keys parameters: - name: clientId in: path required: true schema: $ref: '#/components/schemas/SubClientIdObj' - name: apiKeyId in: path required: true schema: $ref: '#/components/schemas/ApiKeyIdObj' summary: Update API keys for Sub Merchants description: Update API keys operationId: updateApiKeys requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiKeyUpdateObj' responses: '204': description: API key updated '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '401': description: Invalid Authorization header content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: Unauthorized '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny '404': description: Client ID not found content: application/json: schema: $ref: '#/components/schemas/ErrorModel' /client/{clientId}/oauth2: post: security: - SecretKey: [] tags: - API Keys summary: Enable OAuth2 for a client description: Enable OAuth2 for a client operationId: enableClientOAuth2 parameters: - name: clientId in: path required: true description: The Azupay sub-client ID whose OAuth2 configuration is being retrieved. schema: $ref: '#/components/schemas/SubClientIdObj' requestBody: content: application/json: schema: type: object additionalProperties: false description: Optional configuration when enabling OAuth2. Currently has no fields. responses: '201': description: OAuth2 has been enabled and credentials issued. content: application/json: schema: allOf: - $ref: '#/components/schemas/EnableOAuth2ResponseObj' '400': description: Invalid request. The most common cause is that the client is not on the enterprise plan or clientId path parameter is not matching the Authorization header and is therefore not allowed to enable OAuth2. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny get: security: - SecretKey: [] tags: - API Keys summary: Get OAuth2 configuration for a client description: Get OAuth2 configuration for a client operationId: getClientOAuth2 parameters: - name: clientId in: path required: true description: The Azupay sub-client ID whose OAuth2 configuration is being retrieved. schema: $ref: '#/components/schemas/SubClientIdObj' responses: '200': description: The OAuth2 configuration for the client. content: application/json: schema: allOf: - $ref: '#/components/schemas/GetOAuth2ResponseObj' '403': description: Forbidden content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorModel' - properties: message: example: User is not authorized to access this resource with an explicit deny '404': description: OAuth2 is not enabled for this client, or the client does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' components: schemas: GetOAuth2ResponseObj: type: object description: 'Response returned when retrieving the OAuth2 configuration for a client. Identical to `EnableOAuth2ResponseObj` except that `oauth2ClientSecret` is **not** returned because the secret is only ever exposed at enablement time. ' additionalProperties: false required: - oauth2ClientId - oauth2TokenUrl - oauth2GrantType - oauth2TtlInSecs - oauth2AllowedScopes properties: oauth2ClientId: type: string description: The OAuth2 client identifier issued for this Azupay client. example: 3n8q9p1k2l4m5o6p7q8r9s0t1u oauth2TokenUrl: type: string format: url description: The OAuth2 token endpoint to request access tokens from. example: https://auth-uat.azupay.com.au/oauth2/token oauth2GrantType: type: string description: The OAuth2 grant type supported by this client. enum: - client_credentials example: client_credentials oauth2TtlInSecs: type: integer description: The lifetime, in seconds, of access tokens issued for this client. example: 3600 oauth2AllowedScopes: type: array description: The list of OAuth2 scopes that this client is allowed to request. items: type: string example: - RestAPI/GET:balance - RestAPI/GET:paymentRequest - RestAPI/POST:sweepRequest GetApiKeysResponseObj: type: array items: $ref: '#/components/schemas/GetApiKeyResponseObj' apiKeysProvisionObj: type: object additionalProperties: false required: - permissions properties: permissions: type: array items: type: string example: RestAPI/POST/paymentRequest description: List of permissions for api key generateHMAC: type: boolean EnableOAuth2ResponseObj: type: object description: 'Response returned when OAuth2 is successfully enabled for a client. Contains the credentials and metadata required to obtain access tokens via the OAuth2 `client_credentials` grant. The `oauth2ClientSecret` is returned only once at enablement time and cannot be retrieved later. Store it securely. ' additionalProperties: false required: - oauth2ClientId - oauth2ClientSecret - oauth2TokenUrl - oauth2GrantType - oauth2TtlInSecs - oauth2AllowedScopes properties: oauth2ClientId: type: string description: 'The OAuth2 client identifier issued for this Azupay client. Use this value as the `client_id` parameter when requesting an access token from `oauth2TokenUrl`. ' example: 3n8q9p1k2l4m5o6p7q8r9s0t1u oauth2ClientSecret: type: string description: 'The OAuth2 client secret issued for this Azupay client. Use this value as the `client_secret` parameter when requesting an access token from `oauth2TokenUrl`. **This value is returned only once when OAuth2 is enabled and is never returned again by subsequent GET requests. Store it securely.** ' example: abcdef1234567890abcdef1234567890abcdef1234567890abcdef12 oauth2TokenUrl: type: string format: url description: 'The OAuth2 token endpoint. POST to this URL with `application/x-www-form-urlencoded` body containing `grant_type`, `client_id` and `client_secret` to obtain an access token. ' example: https://auth-uat.azupay.com.au/oauth2/token oauth2GrantType: type: string description: The OAuth2 grant type supported by this client. enum: - client_credentials example: client_credentials oauth2TtlInSecs: type: integer description: The lifetime, in seconds, of access tokens issued for this client. example: 3600 oauth2AllowedScopes: type: array description: The list of OAuth2 scopes that this client is allowed to request. items: type: string example: - RestAPI/GET:balance - RestAPI/GET:paymentRequest - RestAPI/POST:sweepRequest apiKeysProvisionResponseObj: type: object description: 'Response object returned upon successful provisioning of a new API key. Contains the newly created API key details including credentials and permissions. ' additionalProperties: false properties: keyID: type: string description: 'A unique identifier assigned to the newly created API key. ' example: SECRE408AB apiKey: type: string description: 'The actual API key string that clients will use for authentication. This should be stored securely by the client, as it is only returned once. ' example: XXXXXXXXX_YYYYYYYYYY_ZZZZZZZZZZZ hmacKey: type: string description: 'The HMAC secret key associated with the API key, used for request signing. Like the apiKey, this should be treated as sensitive and stored securely. ' example: hmac_secret_XXXXXXXXX enabled: type: boolean description: 'Indicates whether the newly provisioned API key is active and usable. ' example: true permittedOperations: type: array description: 'A list of operations or permissions granted to this API key. These define what actions can be performed using the key. ' items: type: string example: RestAPI/POST/paymentRequest example: - RestAPI/POST/paymentRequest - RestAPI/GET/paymentRequest ApiKeyIdObj: type: string example: SECR description: The ID provided when the API Key was generated via the API or from the dashboard. GetApiKeyResponseObj: type: object description: 'Response object that provides detailed information about an existing API key, including its current status, capabilities, and permissions. ' additionalProperties: false properties: keyID: type: string description: 'A unique identifier for the API key. This ID is used to reference and manage the key programmatically. ' example: SECRE408AB hmacEnabled: type: boolean description: 'Indicates whether HMAC-based authentication is enabled for this API key. If true, requests authenticated with this key must be signed using HMAC. ' example: true enabled: type: boolean description: 'Represents whether the API key is currently active and allowed to be used. If set to false, the key is considered disabled and cannot be used for authentication. ' example: true permittedOperations: type: array description: 'A list of operations that the API key is authorized to perform. These may correspond to specific API actions, endpoints, or permission scopes. ' items: type: string example: RestAPI/POST/paymentRequest example: - RestAPI/POST/paymentRequest - RestAPI/GET/paymentRequest ErrorModel: type: object additionalProperties: false required: - message properties: message: type: string details: type: object additionalProperties: false properties: failureCode: type: string failureReason: type: string required: - failureCode - failureReason ApiKeyUpdateObj: type: object description: 'Object used to update API key state (Active / Disabled). ' additionalProperties: false minProperties: 1 required: - enabled properties: enabled: type: boolean description: 'Indicates whether the API key is currently active. Set to `true` to enable the key, or `false` to disable it. ' example: true SubClientIdObj: type: string description: 'Your client’s unique identifier that we provide you during the initial onboarding request. ' minLength: 5 maxLength: 50 example: CLIENT1 securitySchemes: SecretKey: description: 'The secret key is used to access restricted functions and should be stored securely in your system. It is required for operations which may result in additional charges to you as a merchant. Please protect the key by storing it encrypted granting access only to a limited set of users and applications requiring its use. ' in: header name: Authorization type: apiKey DistributableKey: description: 'The distributable key has limited access and may be exposed publicly to your payers. ' in: header name: Authorization type: apiKey