# API Keys And Permissions

API keys control what a backend can do with PayChain. Treat them like production payment credentials.

{% hint style="danger" %}
**Important note:** Never expose PayChain API keys in browser JavaScript, mobile apps, static sites, public repositories, support screenshots, analytics tools, or logs.
{% endhint %}

### Key types

| Key type         | Intended use                                                                        | Fund movement                           |
| ---------------- | ----------------------------------------------------------------------------------- | --------------------------------------- |
| Standard API key | Customers, invoices, reads, balances, transactions, networks, tokens, and webhooks. | Cannot create programmatic withdrawals. |
| Payout API key   | Programmatic withdrawals and approved payout automation from a trusted backend.     | Can move funds within policy.           |

### Standard API keys

Use a standard API key for collection and reconciliation workflows:

* Create customers.
* Create invoices.
* Attach an approved payout route to an invoice.
* Read invoices, balances, transactions, networks, and tokens.
* Configure and inspect webhooks where supported.

Standard API keys should not be able to create withdrawals or mutate dashboard-only controls.

### Payout API keys

Use a payout API key only from a backend service that owns payout approval logic.

Payout keys are appropriate for:

* Programmatic withdrawals.
* Dynamic payout recipients on invoices.
* Backend-controlled treasury movement.

{% hint style="warning" %}
**Payout safety note:** Validate payout destination, order status, amount, customer risk, and business limits in your own backend before sending payout instructions to PayChain.
{% endhint %}

### Payout policy guardrails

Payout API keys should be created for a narrow job, not for broad account access. A payout key can be constrained by policy so that even trusted backend automation has clear limits.

| Policy dimension      | What it controls                                            | Example                                                                        |
| --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Token                 | Which asset can move.                                       | `USDC` only.                                                                   |
| Chain and network     | Which rail can be used.                                     | `evm` on `base-mainnet`.                                                       |
| Destination policy    | Whether destinations must be allowlisted or can be dynamic. | Allowlisted seller wallets, or dynamic receivers for an approved ramp service. |
| Per-withdrawal amount | Maximum amount for one payout.                              | No single payout above `$500`.                                                 |
| Daily cap             | Maximum amount over a rolling day.                          | No more than `$5,000` per day.                                                 |
| Source IP policy      | Optional backend IP restriction.                            | Only requests from production backend IPs.                                     |

If a payout request violates policy, PayChain rejects it before fund movement. Your backend should treat the rejection as a failed business action, show an operator-friendly reason, and avoid blind retries.

#### Debugging payout policy rejections

When a payout API request is rejected:

1. Check the HTTP status and error `code`.
2. Confirm the key type is a payout API key.
3. Confirm token, chain, and `networkId`.
4. Confirm destination policy allows the receiver.
5. Confirm amount and daily cap.
6. Confirm source IP policy if configured.
7. Log the PayChain `requestId` without logging secrets.

{% hint style="info" %}
**Dynamic recipient note:** Dynamic payout recipients are powerful because the receiver can change per invoice. They should only be created from a trusted backend after your system validates the order, receiver, limits, and fraud rules.
{% endhint %}

### Recommended storage

* Store keys in a secret manager or protected environment variables.
* Use separate keys for sandbox and live.
* Use separate keys for collection and payout automation.
* Limit access to production payout keys.
* Rotate keys after suspected exposure or team access changes.

### Logging rules

Do not log:

* API keys.
* Webhook secrets.
* Authorization headers.
* Raw webhook bodies containing sensitive metadata.
* Payout destination auth tokens.
* Full SDK client config.

Log instead:

* Request ID.
* PayChain resource ID.
* Your own order or customer reference.
* Status.
* Environment.
* Timestamp.

### Common mistakes

* Using one production key in every service.
* Putting API keys into frontend code.
* Reusing sandbox webhook secrets in live mode.
* Letting a standard key perform payout-like work through a proxy service.
* Creating dynamic payout recipients from unvalidated client input.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/developer-quickstart/api-keys-and-permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.