Auth Tokens

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How each token is obtained, with code

Overview

The Corporate API uses more than one kind of token, and they are not interchangeable. This page is the
inventory: what each one is, what it unlocks, and how long it lasts.
Authentication is where the flows and code live.

Token	Obtained from	Proves	Unlocks	Lifetime
Partner token	`POST /api/v1/token` (client credentials)	Your company's identity	Four corporation-agnostic endpoints	48 hours
Corporation token	`POST /api/v1/corporations/login`	An employee's identity inside one corporation	Every corporation-scoped endpoint, filtered by that employee's permissions	Per environment; read `exp`
Identity token	Privy or Crossmint, in your front end	The employee's sign-in	Login without `X-User-*` headers — it is not a Wirex credential itself	Set by the provider
Action token	`POST /api/v1/confirmation/signature/verify`	A fresh, deliberate confirmation by the employee	One action type only — card details or 3DS	5 minutes

Only the first two go in the Authorization header. The rest are inputs to a specific call.

client_id + client_secret        →  partner token
partner token + user headers     →  corporation token
corporation token                →  cards, transfers, employees, roles, activities
corporation token + action token →  card PAN / CVV / PIN, 3DS decisions

Which One Do I Need?

You want to	Use
Register a corporation, or log an employee in	Partner token + identity headers
List the corporations an employee belongs to	Partner token + identity headers
Anything else — cards, transfers, employees, roles, activities	Corporation token
Sign employees in with Privy or Crossmint	Identity token, exchanged at login
Read a card PAN, CVV or PIN	Corporation token plus an action token
Approve or decline a 3DS challenge	Corporation token plus an action token

Bearer Tokens

Partner Token

Client-credentials token representing your company, not any employee. HMAC-SHA256, scope
partner:full, 48-hour validity, carrying company_id and azp.

It reaches only the corporation-agnostic endpoints — registration, login, and listing an employee's
corporations. Everything else refuses it. See
Endpoints the Partner Token Reaches.

Cache it until shortly before exp and refresh with a margin. POST /api/v1/token is rate-limited
per IP and per client — back off exponentially on 429.

Corporation Token

Issued by login, and scoped to one employee inside one corporation. It carries the corporation address
and id, the employee id, their role, their permission set and the chain id — which is why requests
carrying it need no identity headers, and why the same call can succeed for one employee and return
CategoryForbidden for another.

An employee belonging to several corporations gets a different corporation token per corporation. See
Choosing a Corporation.

Which of the Two

	Partner token	Corporation token
Represents	Your company	One employee, in one corporation
Reaches	Four endpoints	Every corporation-scoped endpoint
Identity headers	Required	Not needed
Permission-filtered	No	Yes — by the employee's role
Lifetime	48 hours	Read `exp` from the token

Naming across trees. The retail API calls its client-credentials token the S2S token, and its
second-leg scoped token the user token. Same two-step shape, different names — see
Retail Auth Tokens.

Action Tokens

Bearer tokens authenticate the caller. Action tokens prove the employee just deliberately confirmed
a specific thing, and are required on top of a corporation token for sensitive operations.

An action token is minted for one action_type and is rejected by any operation belonging to another.

Action Types

`action_type`	Confirms
`GetCardDetails`	Reading PAN, CVV and PIN
`3dsChallenge`	Approving or declining a 3DS challenge

Values are matched case-insensitively, but send them exactly as written above. An unrecognised value
fails with action_type: Invalid value for action type and issue: invalid_value.

The Corporate API has no SMS confirmation route — signature is the only way to mint an action token.

Obtaining One

POST /api/v1/confirmation/signature/verify

The employee signs this exact message with the wallet's private key:

By signing this I confirm that I am executing action {action_type} at {nonce}

Field	Type	Required	Description
`action_type`	string	Yes	The action being confirmed
`message_signature`	string	Yes	Signature over the message above
`nonce`	integer	Yes	Unix timestamp used when forming the message

EVM and Stellar signatures are both accepted; the chain is taken from the employee's wallet address.

POST /api/v1/confirmation/signature is obsolete and kept for backward compatibility. Use
/signature/verify.

Validity

An action token is valid for 5 minutes and for one action type. One GetCardDetails token unlocks
PAN, CVV and PIN together — mint once per session, not once per field. A 3dsChallenge token unlocks
none of them.

Error	`error_details`	Meaning
`ErrorExpired`	`action_token: expired`	More than 5 minutes old — mint a new one
`ErrorInvalidField`	`action_token: invalid_purpose`	Minted for a different `action_type`
`ErrorInvalidField`	`action_token: invalid_token`	Malformed
`ErrorInvalidField`	`action_token: invalid_claims`	Claims could not be parsed

invalid_purpose is the one that catches integrations out: it is not an expiry and retrying does not
help. Mint a token for the action you are actually performing.

Anonymous Endpoints

These take no Authorization header at all:

Endpoint	Purpose
`GET /api/v1/config`	Client and chain configuration
`GET /api/v1/global/capabilities`	Capability matrix per country
`GET /api/v1/validation/rules`	Field validation regexes

Handling

Store client_secret in a secrets manager. Never in source control, never in client-side code
Cache the partner token until shortly before expires_at; refresh with a margin
A corporation token carries an employee's permissions — treat it as that employee's credential
Never log a full token; truncate for debugging
Use HTTPS with TLS 1.2 or later and validate certificates
Do not mint action tokens speculatively. They last 5 minutes and are tied to one action