> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paylinedata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials and request safety

> Use environment-local credentials, show-once delivery and deliberate replacement.

## Issue, replace and revoke

Payline must admit your organization and integration first. An admitted organization
manager opens **Account → Developer Settings** from the partner access page.
Check the organization, integration, environment and API base URL before issuing.
Secrets are shown once by the application: copy the secret into your server's secret
store before selecting **Done** or leaving the dialog. Switching tabs can hide it.
There is no later application secret-reveal operation.

A replacement keeps the same stable integration identity. Move your server to
the replacement, confirm the cutover, then explicitly revoke the predecessor;
replacement alone does not revoke it. Revocation denies new requests using that
key, but does not cancel an already authenticated operation or revoke merchant URLs.
An authorized manager can still revoke credentials after integration use is disabled.

If delivery is interrupted, use **Check status**. Do not blindly issue again. The
application reconciles the attempt and revokes an identified undelivered key before
allowing fresh issuance. If it remains uncertain, contact Payline without sharing secrets.

## Authenticate from your server

Send `Authorization: Bearer <key>` on each API request. JSON writes use
`Content-Type: application/json`. The verified credential and current local grant
determine tenant, environment, integration and capabilities; request fields cannot
select them. The relevant capabilities are `applications:create`,
`applications:read`, `applications:eligible-users:read` and
`applications:handoff:reissue`.

For the shell examples, supply `PAYLINE_API_KEY` through your approved secret
manager; do not type a real key into shell history. Disable shell tracing. Each
example uses the Sandbox base below and requires `curl`; commands that inspect
JSON also use `jq`.

```bash theme={null}
set +x
umask 077
export PAYLINE_API_BASE='https://sandbox.paylinedata.com/api/v1'
: "${PAYLINE_API_KEY:?Load the Sandbox key through your secret manager}"
```

The commands save responses to restricted local files instead of printing protected
answers or merchant URLs. Use a private working directory and delete local response
files when no longer needed under your retention policy. Do not send them to telemetry,
shared build logs or support. Do not paste API keys into browser code, URLs or chat.

## Errors, limits and retries

Errors contain a safe `error.code`, `error.message`, field paths/codes,
`error.retryable` and a `supportReference`. Field errors do not echo submitted values.
Share only safe support references and the operation/time when asking for help.

| Response | Action |
| - | - |
| `401 unauthenticated` | Check the correct environment and credential; do not retry indefinitely. |
| `403 capability_denied` | Confirm current admission and capability with Payline. |
| `404 not_found` | Check the identifier and authorized integration scope. |
| `409 request_conflict` | The request ID was reused with different intent. Reconcile the original operation. |
| `422 validation_failed` | Correct the reported fields before a new valid operation. |
| `429 rate_limited` | Wait for `Retry-After` before retrying. |
| `503 operation_unconfirmed` or a lost response | For create/reissue, retry the identical request ID and original body after backoff. Never generate a new ID just because the response was lost. |

Per stable caller, the implementation allows 30 create attempts, 30 separate
reissue attempts and 120 shared GET attempts per 60-second window. Replacement
keys do not reset these counters. Poll with backoff; these limits are not a throughput SLA.
Responses are `no-store`; your own clients must also avoid caching sensitive results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.