Authentication

Every request to the Axra Pay API must be authenticated. Axra supports two methods: passing your API key directly in a request header, or exchanging your key and secret for a short-lived JWT token. Both methods work for all endpoints — choose the one that fits your architecture.

Method 1: API key header

The simplest way to authenticate is to include your API key in the x-api-key header on every request. This approach works well for server-side integrations where your API key is stored securely in an environment variable.

x-api-key: bk_live_abc123...

Example request:

curl -X POST https://api.useaxra.com/api/v1/business/checkout/session \
  -H "x-api-key: bk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "customerEmail": "customer@example.com",
    "successUrl": "https://yoursite.com/success"
  }'

Never expose your API key in client-side code, public repositories, or frontend JavaScript. Always make Axra Pay API calls from your server.

Method 2: JWT token exchange

For integrations that prefer short-lived credentials, you can exchange your apiKey and apiSecret for a JWT bearer token. The token expires after one hour and must be refreshed before it does.

Your webhookSecret doubles as your apiSecret for token authentication. They are the same credential.

Step 1: Request a token

Send a POST request to /business/auth/token with your apiKey and apiSecret in the request body.

curl -X POST https://api.useaxra.com/api/v1/business/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "bk_live_abc123...",
    "apiSecret": "bs_live_xyz789..."
  }'

const response = await fetch(
  'https://api.useaxra.com/api/v1/business/auth/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apiKey: 'bk_live_abc123...',
      apiSecret: 'bs_live_xyz789...',
    }),
  }
);

const { accessToken, expiresIn } = await response.json();

Request body parameters:

string

required

Your business API key. Starts with bk_live_ for production or bk_test_ for sandbox.

string

required

Your API secret. This is the same value as your webhookSecret.

Step 2: Read the response

A successful request returns the following fields:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "businessId": "biz_01H...",
  "businessName": "Acme Corp"
}

string

required

The JWT token to include in subsequent requests.

string

required

Always "Bearer". Use this as the prefix in your Authorization header.

number

required

Token lifetime in seconds. Always 3600 (one hour).

string

The unique identifier for your business profile.

string

Your registered business name.

Step 3: Use the token

Include the accessToken in the Authorization header of every subsequent request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Example authenticated request:

curl -X GET https://api.useaxra.com/api/v1/business/payments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refresh your token before it expires by calling POST /business/auth/token again with the same credentials. Build a refresh mechanism into your application rather than handling 401 errors reactively.

Token error responses

HTTP status	Meaning
`401 Unauthorized`	The `apiKey` or `apiSecret` is invalid.
`400 Bad Request`	The request body is missing `apiKey` or `apiSecret`.

Getting your credentials

Create an account

Copy your credentials immediately

Your apiKey (format: bk_live_...) and webhookSecret are shown only once when your account is created. Copy both values to a secure password manager or secrets vault before leaving the page.

Store credentials securely

Never hard-code credentials in your source code. Store them as environment variables or in a secrets management service such as AWS Secrets Manager, HashiCorp Vault, or your hosting provider’s secret store.

Regenerate a lost API key

If you lose your API key, call POST /business/regenerate-api-key to issue a new one. Your previous key is immediately invalidated — update any running services before regenerating.

curl -X POST https://api.useaxra.com/api/v1/business/regenerate-api-key \
  -H "x-api-key: bk_live_your_current_key"

Axra stores API keys as SHA-256 hashes. Your raw key is never stored on Axra’s servers, which is why it cannot be retrieved after creation — only regenerated.

Choosing an authentication method

	API key header	JWT token
Setup complexity	Minimal	Requires token exchange and refresh logic
Best for	Server-side integrations, scripts, internal tools	Architectures that require short-lived credentials
Token lifetime	Long-lived (until regenerated)	1 hour
Revocation	Regenerate key to invalidate	Tokens expire automatically

For most server-side integrations, the API key header is the simplest and most practical choice. Use JWT tokens if your security policy requires credentials that expire automatically.

Overview

Reference

Authentication

Method 1: API key header

Method 2: JWT token exchange

Step 1: Request a token

Step 2: Read the response

Step 3: Use the token

Token error responses

Getting your credentials

Choosing an authentication method

Next steps

Payments

Checkout Sessions

​Method 1: API key header

​Method 2: JWT token exchange

​Step 1: Request a token

​Step 2: Read the response

​Step 3: Use the token

​Token error responses

​Getting your credentials

​Choosing an authentication method

​Next steps

Payments

Checkout Sessions

Method 1: API key header

Method 2: JWT token exchange

Step 1: Request a token

Step 2: Read the response

Step 3: Use the token

Token error responses

Getting your credentials

Choosing an authentication method

Next steps