- A bearer access token in the
Authorizationheader. - The mandatory
X-Api-Versionheader (see Versioning).
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 aclient_id and a client_secret. For the full walkthrough, see API keys and Sign in to Shift.
Exchange credentials for an access token
CallPOST /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 mandatoryX-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.
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.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.
Security checklist
- Store the
client_secretin 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_secretor the access token. - Log token usage on your side (request ID, timestamp). Go through it first if you suspect misuse.
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.