Authentication

Overview

All AWDPay APIs are protected by short-lived bearer tokens. Merchants authenticate by exchanging their console-issued apiKey and secretKey for an access token, then attach that token to every API call until it expires.

Credential lifecycle

1. Generate keys – In the AWDPay dashboard, create an API key pair for Sandbox or Production. Store the secretKey in a vault (AWS Secrets Manager, HashiCorp Vault, etc.).
2. Compliance approval – Upload KYB/KYC documents. Production credentials stay disabled until the AWDPay risk team validates your profile.
3. Server-side exchange – From a trusted backend only, call the token endpoint with apiKey + secretKey.
4. Attach tokens – Add the Authorization: Bearer <token> header to every Collections, Disbursement, Transfers, or webhook-subscription request.
5. Renew – Tokens expire quickly (default 15 minutes). Refresh them proactively before expiry or retry with a fresh token when you receive 401 invalid_token.

Token endpoint

Method	Path	Auth payload
POST	/api/auth/token	{ "apiKey": string, "secretKey": string }

• Sandbox base URL: https://sandbox.awdpay.com
• Production base URL: https://api.awdpay.com (or the regional hostname communicated by AWDPay)

Example request:

curl -X POST "$API_BASE_URL/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "merchant_api_key",
    "secretKey": "merchant_secret_key"
  }'

Successful response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "issuedAt": "2025-11-20T09:02:14Z"
}

• expiresIn is expressed in seconds; AWDPay currently issues 15-minute tokens.
• Tokens are opaque JWTs—treat them as secrets and never expose them in mobile apps or client-side logs.

Using the token

Attach the bearer token to each API request until it expires. The example below shows how to list the enabled payment gateways for Collections (you can substitute any other AWDPay endpoint):

# Example: list payment gateways available to the merchant
curl -X GET "$API_BASE_URL/api/gateways?flow=collections" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

// Example helper that authenticates, then lists gateways
const API_BASE_URL = process.env.AWDPAY_API_BASE_URL ?? 'https://sandbox.awdpay.com';

async function fetchGateways(flow = 'collections') {
  const tokenResponse = await fetch(`${API_BASE_URL}/api/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ apiKey: process.env.AWDPAY_API_KEY, secretKey: process.env.AWDPAY_SECRET })
  });
  const { token } = await tokenResponse.json();

  const response = await fetch(`${API_BASE_URL}/api/gateways?flow=${flow}`, {
    headers: {
      Authorization: `Bearer ${token}`
    }
  });
  return response.json();
}

Token lifecycle & retry strategy

• Proactive refresh – Cache the token in memory/Redis and refresh it 60 seconds before expiresIn.
• Graceful retry – If an API call returns 401 or 403 with invalid_token, request a new token once and replay the original request.
• Key rotation – Rotate secretKey at least every 90 days. AWDPay allows overlapping keys so you can issue a new one, deploy, then revoke the old key without downtime.
• Concurrency – Use idempotency keys on write operations so that retries caused by token refreshes stay safe.

Security best practices

• Do not embed apiKey or secretKey in front-end code or mobile binaries.
• Restrict outbound traffic so only your API tier can reach AWDPay token endpoints.
• Enable TLS 1.2+ and certificate pinning where possible; reject responses if the certificate chain changes unexpectedly.
• Log token issuance events with request IDs for auditing, but never log raw tokens or secrets.
• Revoke compromised keys immediately through the AWDPay dashboard and purge cached tokens.