Authentication

Nexpay accepts two authentication schemes, depending on who is calling the API:

• X-API-Key — for server-to-server (M2M) traffic. This is what you'll use for almost every integration. See API keys for how to issue, list, and revoke keys.
• Authorization: Bearer <token> — for browser sessions, where a human user has logged into the Nexpay Dashboard. Tokens are issued by POST /v2/auth/login and short-lived. Not typically used by integrations.

Requests without one of these headers, or with an invalid value, return 401.

Server-to-server (API key)

Combine your clientId and secret with a colon and send them on the X-API-Key header:

curl 'https://api.nexpay.com.au/v2/users/me' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'

const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': `${process.env.NEXPAY_CLIENT_ID}:${process.env.NEXPAY_SECRET}`,
};

const response = await fetch('https://api.nexpay.com.au/v2/users/me', {
  method: 'GET',
  headers,
});

if (response.ok) {
  const { data } = await response.json();
  console.log(data.email);   // "api-key:nxp_ck_787f5b97469f65c4ca97da31"
  console.log(data.roles);   // ["APIKey"]
  console.log(data.tenantId);
} else {
  // 401 [AUT0001] — missing / wrong scheme
  // 401 [AUT0003] — present but invalid key (typo, revoked, or wrong format)
  throw new Error(`Auth failed: ${response.status}`);
}

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->get('https://api.nexpay.com.au/v2/users/me');

if ($response->successful()) {
    $data = $response->json('data');
    echo $data['email'];    // "api-key:nxp_ck_787f5b97469f65c4ca97da31"
    echo $data['roles'][0]; // "APIKey"
    echo $data['tenantId'];
} else {
    // 401 [AUT0001] — missing / wrong scheme
    // 401 [AUT0003] — present but invalid key (typo, revoked, or wrong format)
    throw new Exception("Auth failed: {$response->status()}");
}

The clientId:secret separator is a single colon. Don't URL-encode it, don't base64-encode it — send the raw pair.

Browser sessions (Bearer token)

Browser apps that go through POST /v2/auth/login receive an encrypted, short-lived Bearer token. Subsequent requests include it on the Authorization header:

const response = await fetch('https://api.nexpay.com.au/v2/users/me', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
  },
});

You'll only need this scheme if you're building against the Nexpay Dashboard's session model (for example, an admin tool that acts on behalf of a logged-in human). For machine integrations, use API keys.

Sandbox vs production

Both base URLs accept the same auth schemes, but keys are environment-scoped:

• Production — https://api.nexpay.com.au
• Sandbox — https://sandbox-api.nexpay.com.au

A clientId:secret pair issued in sandbox does not work in production and vice-versa. Issue separate keys per environment from the matching dashboard.

Identity types

A request authenticates as one of:

Human user

A natural person who signed into the dashboard. Carries roles such as Agent, Admin, etc. Used for browser sessions and for issuing/revoking API keys.

API key (shadow user)

Each API key is backed by a dedicated "shadow" user on the legacy platform. Calls authenticated via X-API-Key carry the role APIKey and the tenantId of the issuing organisation. Machine actions are attributed to the key (not the human who created it) in the audit log — lastUsedAt updates on every call.

API keys cannot create or revoke other API keys; only human-session users can.

Roles and permissions

Permissions are derived from the user's roles and the tenant's payment policy. The effective set is published on GET /v2/users/me under paymentAccess / organizationPaymentPolicy — query this once during integration setup to discover what your key is authorised to do (for example, whether it can create split payments or run multi-payee quotes).

API keys do not automatically have super-admin access — their effective permissions follow the roles passed at creation time and the tenant policy. Confirm by inspecting the paymentAccess block on /v2/users/me.

Authentication errors

Error responses use the standard envelope: { statusCode, code, message, timestamp }. See Errors.