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

# Authentication

> How to authenticate with Paymnt Cloud API

All **server-side** requests to Paymnt Cloud use **API keys**. Send your secret key in the `api-key` header. If you use routing **profiles**, include `x-profile-id`.

* **Production:** `https://api.paymnt.cloud`
* **Sandbox:** `https://sandbox.paymnt.cloud`

> Never expose secret keys in browsers or mobile apps. Keep keys in your server environment variables or your secret manager.

***

## Headers

```text theme={null}
api-key: <YOUR_SECRET_KEY>
x-profile-id: <pro_...>   # optional, only if profiles are enabled
Idempotency-Key: <uuid-v4>   # recommended for POST/PUT/PATCH
```

* **api-key** — required for all authenticated calls
* **x-profile-id** — lets you target a specific routing/profile configuration
* **Idempotency-Key** — prevents duplicate processing on retries for mutating requests

See also: [Profiles](/pages/platform/profiles) • [Idempotency](/pages/essentials/idempotency)

***

## Key scope & environments

* **Keys are environment-scoped.** Create separate keys for Sandbox and Production
* **Rotate keys periodically;** remove old keys from all deployments
* **Limit who can view/rotate keys** via RBAC. See [RBAC & Keys](/pages/security/rbac-keys)
* **For local dev and CI/CD,** load keys via environment variables. See [Environments](/pages/environments)

***

## Using the API Reference (Try it)

In the API reference tab, open any endpoint and use Try it.
Enter your api-key (and x-profile-id if used) once; it will be applied to subsequent requests.
If your OpenAPI lists both servers, you can switch between Sandbox and Production from the server selector.

Browser-based calls originate from your docs domain (e.g., [https://docs.paymnt.cloud](https://docs.paymnt.cloud)). Ensure CORS allows that origin only if you plan to call your API from the docs.

***

## Examples

### cURL — list customers

```bash theme={null}
curl -X GET "https://api.paymnt.cloud/customers" \
  -H "Accept: application/json" \
  -H "api-key: <YOUR_SECRET_KEY>" \
  -H "x-profile-id: <pro_...>"    # optional
```

### cURL — create payment (with idempotency)

```bash theme={null}
curl -X POST "https://api.paymnt.cloud/payments" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_SECRET_KEY>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000001" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "description": "Order #1001"
  }'
```

### Node (fetch)

```javascript theme={null}
const base = process.env.PAYMNT_BASE_URL || "https://sandbox.paymnt.cloud";

const res = await fetch(`${base}/customers`, {
  headers: {
    "Accept": "application/json",
    "api-key": process.env.PAYMNT_API_KEY,
    ...(process.env.PAYMNT_PROFILE_ID ? { "x-profile-id": process.env.PAYMNT_PROFILE_ID } : {})
  }
});

const customers = await res.json();
console.log(customers);
```

### Python (requests)

```python theme={null}
import os, requests

base = os.getenv("PAYMNT_BASE_URL", "https://sandbox.paymnt.cloud")
headers = {
    "Accept": "application/json",
    "api-key": os.getenv("PAYMNT_API_KEY"),
}
profile_id = os.getenv("PAYMNT_PROFILE_ID")
if profile_id:
    headers["x-profile-id"] = profile_id

r = requests.get(f"{base}/customers", headers=headers, timeout=30)
print(r.status_code, r.json())
```

***

## Errors

* **401 Unauthorized** — missing/invalid api-key
* **403 Forbidden** — the key is valid but not permitted for the action/profile

Log the request\_id from error bodies for support and correlation. See [Error Codes](/pages/essentials/error-codes).

***

## Good practices

* **Keep keys server-only;** never hardcode them in client apps
* **Use idempotency** for all mutating requests; implement retry with jitter for transient failures
* **Store keys in a secret manager;** rotate on a schedule; monitor usage
* **Separate Sandbox vs Production** keys and configs; do not reuse across environments. See [Environments](/pages/environments)