Authentication
The Payments AI Public API authenticates every request with an API key passed in the Authorization header.
API key format
Your credentials come in three parts: accountId, apiKey, and apiKeyId. Concatenate them with underscores and pass them in the Authorization header prefixed with ApiKey:
Authorization: ApiKey <accountId>_<apiKey>_<apiKeyId>
The separator between all three parts is an underscore (_). The full string is a single value. Do not URL-encode or base64 it.
Example:
curl 'https://staging-api.payments.ai/v1/public-api/organizations/{organizationId}/subscriptions' \
-H 'Authorization: ApiKey acc_abc123_key_xyz789_kid_def456'
To learn where to obtain the three parts and how the temporal-to-permanent key exchange works, see API key generation.
Tokenization API
The Tokenization API uses a different authentication pattern. The organizationId is passed as an X-Organization-Id header instead of in the URL path. See Base URLs.
Common authentication errors
| Status | Meaning | Common cause |
|---|---|---|
401 Unauthorized | The key is wrong, malformed, or expired. | Wrong concatenation, missing ApiKey prefix, missing underscore separator, or a revoked key. |
403 Forbidden | The key is valid but does not have permission for the requested operation. | Account-level permissions, key scope, or organization mismatch. |
If you get a 401 error immediately after rotating a key, check that your environment variables use the new key instead of a cached old value.
Security rules
- Store API keys in backend environment variables only. Never put them in frontend code or client-side JavaScript.
- Never commit API keys to source control. Use a secrets manager or environment-variable injection.
- PAI does not store or log the secret or the permanent API key. Save them immediately when they are generated, as there is no recovery option if they are lost.
- Rotate the secret every 90 days. See API key generation: key rotation.