Partner API Key

The partner API key is a per-tenant, server-to-server credential that lets your backend call the Paysense admin API without an interactive user login. It is the REST counterpart to the UI Integration iframe flow: both mint short-lived, user-scoped tokens, but this path is driven entirely by request headers.

Use it to:

Mint an access token on behalf of one of your users.
Refresh that access token when it expires.
Create users in your tenant.
Trigger a password reset for a user.

Prerequisites

Item	Description
Tenant subdomain	The Paysense host your tenant is served from (e.g. `acme.iopayroll.com`). The subdomain determines which tenant the request runs against.
Client ID	Your public client identifier, sent as `Tenant-Key-1`.
API key secret	Your secret key, sent as `Tenant-Key-2`. Delivered through a secure channel.

Authentication

Send both headers on every admin API call:

Header	Value
`Tenant-Key-1`	Your client identifier
`Tenant-Key-2`	Your secret key

The tenant is resolved from the request's subdomain, and your credentials must belong to that tenant. A key issued for one tenant cannot be used against another tenant's subdomain.

note

Tenant-Key-1 and Tenant-Key-2 are placeholders on this page. The header names to send are supplied with your credentials in the partner integration pack - substitute them in the examples below.

warning

The API key secret is a server-side credential. Never expose it to browser code or embed it in a mobile app - anyone holding it can mint tokens for users in your tenant.

Get a user token

Exchanges your API key for an access token and refresh token scoped to a single user in your tenant.

POST /api/admin/authentication/token

curl -X POST https://acme.iopayroll.com/api/admin/authentication/token \
  -H "Tenant-Key-1: <your-client-id>" \
  -H "Tenant-Key-2: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "username": "user@example.com" }'

The returned access token is scoped to the requesting user and to your tenant. If a user belongs to more than one tenant, the token issued through your API key only ever grants access to your tenant.

Use the access token as a normal bearer token on subsequent API calls:

Authorization: Bearer <accessToken>

Refresh a token

POST /api/admin/authentication/refresh

curl -X POST https://acme.iopayroll.com/api/admin/authentication/refresh \
  -H "Tenant-Key-1: <your-client-id>" \
  -H "Tenant-Key-2: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "<refreshToken>" }'

note

The refresh call requires the same Tenant-Key-1 / Tenant-Key-2 headers, against the same tenant subdomain, as the original token call. The refresh token alone is not sufficient - Paysense re-derives the tenant from your credentials on every refresh, so a refresh token minted for one tenant cannot be redeemed against another.

Create a user

Provisions a user in your tenant so they can be issued tokens or used in the embed flow.

POST /api/admin/users

email, firstName and lastName are required. displayName, phoneNumber and timeZone (IANA, e.g. Australia/Sydney) are optional.

curl -X POST https://acme.iopayroll.com/api/admin/users \
  -H "Tenant-Key-1: <your-client-id>" \
  -H "Tenant-Key-2: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "user@example.com",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "timeZone": "Australia/Sydney"
      }'

Returns 201 Created. A user that already exists returns 409 Conflict.

Reset a user's password

Returns a password-reset action URL you can deliver to the user.

POST /api/admin/users/{email}/reset-password

curl -X POST https://acme.iopayroll.com/api/admin/users/user@example.com/reset-password \
  -H "Tenant-Key-1: <your-client-id>" \
  -H "Tenant-Key-2: <your-api-key>"

Errors

Status	Meaning
`400`	Malformed request body or missing required fields.
`401`	Missing or invalid `Tenant-Key-1` / `Tenant-Key-2`, or credentials that don't belong to the tenant in the request subdomain.
`409`	The user already exists (user creation only).

Errors are returned as RFC 7807 problem details. Full schemas for every endpoint are in the API Reference.

Security model

Server-side only. The API key is a backend credential; it must never reach client code.
Tenant-bound. Credentials are validated against the tenant resolved from the request subdomain. Cross-tenant use is rejected.
Single-tenant tokens. Tokens minted through the API key are narrowed to your tenant, even for users who belong to several tenants, and the exchange fails closed if that narrowing cannot be guaranteed.
Short-lived access tokens. Refresh through the endpoint above rather than holding long-lived tokens.
User-scoped, not admin-scoped. The API key itself carries no user identity. It can only be used to mint tokens for users in your tenant, which carry that user's own permissions.

Getting started

Partner API key access requires a partnership agreement.

Contact your Paysense partner manager (or reach out via the website) to discuss your use case.
Once your tenant is provisioned, you'll receive your client ID and API key secret through a secure channel.
Build against a staging tenant. Paysense provides a sandbox environment for end-to-end verification before production.

Prerequisites​

Authentication​

Get a user token​

Refresh a token​

Create a user​

Reset a user's password​

Errors​

Security model​

Getting started​