OAuth authentication

Payabli supports OAuth2 for authenticating API requests. Your integration provisions a client ID and client secret, exchanges them for a short-lived Bearer access token, and sends that token on subsequent API calls. This is a server-to-server flow: the credentials and the token stay on your backend.

How it works

The flow has three steps:

1. Provision credentials in the Payabli Portal. You receive a client ID and client secret, scoped to an environment.
2. Request an access token by exchanging your credentials at the token endpoint.
3. Call the API with the token in the Authorization header.

The access token is short-lived. When it expires, request a new one with the same credentials.

Step 1: Provision credentials

Credentials are created and managed in the Payabli Portal. Create an API Authentication credential, which issues:

• A client ID, which identifies your integration.
• A client secret, which authenticates it.

When you create the credential, you set a credential lifetime: how long the client ID and secret stay valid before you must rotate them. You can set the lifetime to 30, 60, 90, or 120 days, or 1 year; 90 days is recommended. This is separate from the access token’s lifetime. The token you request in Step 2 is short-lived; its exact lifetime is returned in the response’s expires_in field (for example, one hour in sandbox) and can differ by environment. Read expires_in rather than assuming a fixed lifetime. The credential lifetime governs the client ID and secret themselves.

The permissions that determine which endpoints and actions the credential can access are also assigned at this stage. Credentials are environment-scoped: you get separate credentials for sandbox and for production.

For step-by-step instructions to create and manage credentials in the portal, see Manage API credentials.

Step 2: Get an access token

Exchange your client ID and client secret for an access token at the token endpoint. The example below uses sandbox; in production, call https://api.payabli.com/api/v2/Token/serverside.

1
curl -X POST https://api-sandbox.payabli.com/api/v2/Token/serverside \
2
     -H "Content-Type: application/json" \
3
     -d '{
4
  "clientId": "YOUR_CLIENT_ID",
5
  "clientSecret": "YOUR_CLIENT_SECRET"
6
}'

A successful response returns the token and its lifetime in seconds:

1
{
2
  "token_type": "Bearer",
3
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.token",
4
  "expires_in": 3600
5
}

If the credentials are invalid, the endpoint returns 400 with an error body:

1
{
2
  "errorType": "InvalidCredentials",
3
  "errorMessage": "Invalid client credentials."
4
}

Step 3: Make authenticated API calls

Send the access token as a Bearer token in the Authorization header on every request:

$
curl https://api-sandbox.payabli.com/api/v2/... \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

When a token expires, the API responds with 401 Unauthorized. Request a new token and retry the call.

Scopes and permissions

A credential’s permissions control which endpoints and actions a token can access. By default, a token carries all the permissions granted to the credential that requested it.

To request a token scoped to a subset of those permissions, pass a permissions array of permission IDs in the token request:

1
{
2
  "clientId": "YOUR_CLIENT_ID",
3
  "clientSecret": "YOUR_CLIENT_SECRET",
4
  "permissions": ["00000000-0000-0000-0000-000000000000"]
5
}

Rotate and revoke credentials

Rotate a client secret or revoke a credential in the Payabli Portal. Rotate before the credential lifetime expires, or any time a secret may be compromised. Rotating issues a new secret and invalidates the old one; revoking disables the credential entirely. Tokens already issued remain valid until they expire, so rotate or revoke and then re-authenticate to pick up the change.

See Refresh credentials to rotate a secret and Delete credentials to revoke access.