Skip to main content
Every Paylead API call carries two things:
  1. A bearer access token in the Authorization header.
  2. The mandatory X-Api-Version header (see Versioning).
Why this matters. Leaked credentials grant access to your Program data. Treat your API client secret like a password: store it in a secret manager, and never commit it to source control.

How authentication works

Authentication is a two-step model. You hold long-lived client credentials and exchange them for short-lived access tokens.
1

Generate an API key in Shift

In Shift, generate an API key for your service. Shift returns a client_id and a client_secret (prefixed sk_…). The secret is shown once; copy it into your secret manager immediately.
2

Exchange the credentials for an access token

Call the token endpoint (POST /tokens) and authenticate with HTTP Basic: the client_id is the username, the client_secret is the password. The request carries no body. Paylead returns a short-lived access token plus an expires_in, the TTL set on the API key (3600 seconds by default).
3

Call the API with the token

Send the access token as a bearer credential, together with the X-Api-Version header. Refresh the token by calling the token endpoint again before it expires.

Credentials vs. tokens

These are two different things; keep them straight: Send the client_secret only to the token endpoint, never on a regular API call.

Get your API client credentials

Generate an API key in Shift (one per environment) under My account > Developers > API Keys. Shift returns a client_id and a client_secret. For the full walkthrough, see API keys and Sign in to Shift.

Exchange credentials for an access token

Call POST /tokens and authenticate with HTTP Basic, not with a JSON payload: The credentials travel in the Authorization header, never in the payload. The response carries the access token and its lifetime (expires_in, in seconds). Cache the access token until shortly before expires_in elapses, then request a new one, rather than calling the token endpoint on every API request.
Code examples coming soon. The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.

Call the API

Pass the access token as a bearer credential and set the mandatory X-Api-Version header. All calls must use HTTPS.
Code examples coming soon. The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
A call without a valid token returns 401 Unauthorized. A call missing the X-Api-Version header is rejected; see Versioning. See Errors for the full list.

Sandbox vs. production credentials

Sandbox and production credentials are separate. A sandbox client cannot mint tokens that work against production, and the reverse.
Use distinct secret-manager entries for each environment. Mixing them risks pointing your staging environment at production data.

Rotate credentials

Access tokens expire on their own at the end of the API key’s TTL, so there is nothing to rotate there. What you protect and rotate is the client secret.
1

Create a new client

In Shift, generate a new API key for the same environment. It returns a fresh client_id and client_secret.
2

Roll the new credentials to your service

Update the secret in your secret manager. Redeploy or hot-reload the services that read it, so they exchange the new secret at the token endpoint.
3

Verify traffic is on the new client

Watch your logs. Confirm requests are succeeding with tokens minted from the new secret.
4

Revoke the old client

Revoke the old API key in Shift. It can no longer issue tokens, and tokens it already issued expire at the end of their TTL.
Keep both clients active during rotation, and revoke the old one only after the new one is verified in production traffic, to avoid downtime if the rollout fails.

Security checklist

  • Store the client_secret in a secret manager (Vault, AWS Secrets Manager, GCP Secret Manager). Never in code, never in environment files committed to Git.
  • Restrict who can generate API keys in Shift. Audit who holds the Technical role.
  • Use a separate API client per service. If one service is compromised, you revoke one client, not all.
  • Never log the client_secret or the access token.
  • Log token usage on your side (request ID, timestamp). Go through it first if you suspect misuse.
If a client_secret leaks, revoke that API key in Shift immediately. Tokens it already issued stay valid until the end of their TTL (3600 seconds by default). Then audit the previous 30 days of API activity in your own logs for unexpected calls.

What’s next

Versioning

The mandatory X-Api-Version header and the version policy.

Rate limits

Per-token request limits and backoff strategy.

Errors

Diagnose 401, 403, and other auth-related failures.

Environments

Switch from sandbox to production safely.