Authentication

ZTL uses OAuth 2.0 client credentials for server-to-server API access. Request credentials from ZTL and exchange them only from a trusted backend.

Token endpoints

Environment	Base URL
Sandbox	https://oidc.sandbox.ztlpay-test.io
Production	https://oidc.ztlpay.io

Append /v2/connect/token to the base URL. The request and environment-specific scope are defined in the generated authentication reference. Use a token from the issuer that matches the API environment:

API environment	Token URL	Scope
Sandbox	https://oidc.sandbox.ztlpay-test.io/v2/connect/token	api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default
Production	https://oidc.ztlpay.io/v2/connect/token	api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default

Example request for Sandbox:

curl --request POST \
  --url https://oidc.sandbox.ztlpay-test.io/v2/connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default'

Send the access token on API requests:

Authorization: Bearer ACCESS_TOKEN

Token lifecycle

• Cache a token securely and reuse it instead of requesting one for every API call.
• Refresh shortly before expires_in elapses.
• On 401 Unauthorized, invalidate the cached token, obtain one replacement, and retry the authenticated call once.
• Never expose a client secret or access token to the end user’s browser.