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, shown once)

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	Missing or malformed body
401	Invalid credentials
403	Partner account is not active

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.

:::tip Caching tokens Cache tokens in your server's process memory or a shared cache (Redis, Memcached). Refresh 1–2 minutes before expires_at to avoid mid-request expiries. :::

Rotation

Regenerating your API key pair immediately invalidates the old private key. Any JWT issued before rotation remains valid until its natural expiry (~15 min) — there is no token revocation endpoint by design, since the short TTL bounds the blast radius.

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.