Authentication

The Partner API uses short-lived JWTs exchanged from a long-lived API key pair.

Obtaining a token

POST /v1/authentications

Request

{
  "public_key": "pk_live_...",
  "private_key": "sk_live_..."
}

Field	Type	Required	Description
public_key	string	Yes	Your partner public key
private_key	string	Yes	Your partner private key (never stored in plaintext, only a bcrypt hash is kept; shown once at generation)

Response 200

{
  "success": true,
  "jwt_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-03-27T16:00:00Z",
  "partner_id": "018e4b2a-1234-7def-abcd-000000000001"
}

Error responses

Status	Meaning
400	Malformed JSON body, or public_key / private_key missing
401	Invalid credentials, or the partner account is not active

The error body is a JSON object with a single error string (for example {"error": "Invalid credentials"}). Note that an inactive (suspended or terminated) partner returns 401, not 403: all authentication failures collapse into 401 so the endpoint never reveals whether a key exists.

Using the token

Pass the token as a Bearer header on every subsequent request:

Authorization: Bearer <jwt_token>

Token expiry

Tokens are valid for 15 minutes. When expired, requests return 401. Obtain a new token by calling POST /v1/authentications again. The API key pair itself does not expire, rotate it any time from the Partner Portal.

Rotation

Regenerating your API key pair immediately invalidates the old private key. It also revokes every JWT issued before the rotation: the API stamps a rotation timestamp on the partner and rejects any token minted earlier (by its iat claim) with 401. There is no separate token-revocation endpoint, key rotation is itself the revocation mechanism, and the short 15-minute TTL bounds the window for any token you do not explicitly rotate away.

Live vs test keys

Every partner has two independent key pairs:

Mode	Public key	Secret key
Live	pk_live_…	sk_live_…
Test (sandbox)	pk_test_…	sk_test_…

Authenticating with your test keys against the same POST /v1/authentications endpoint returns a token scoped to your isolated sandbox, sandbox data never touches live, and vice-versa. See Testing in sandbox for the full workflow.