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

# Authentication

> How to authenticate requests to the Payracle API

Payracle uses two kinds of API keys, each with a live and test variant. Find both in your dashboard under **Developer › API Keys**.

| Key        | Prefix                        | Where it's used                    | Can call                         |
| ---------- | ----------------------------- | ---------------------------------- | -------------------------------- |
| Secret key | `sk_live_...` / `sk_test_...` | Your own backend, server-side only | Every endpoint below             |
| Public key | `pk_live_...` / `pk_test_...` | Client-side (browser, mobile app)  | **Only** checkout initialization |

## Secret key

Pass it as a Bearer token on every request:

```http theme={null}
Authorization: Bearer sk_live_YOUR_SECRET_KEY
```

```bash theme={null}
curl -X GET "https://api.payracle.com/api/v1/virtual-accounts" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

<Warning>
  Never expose your secret key in client-side code, browser JavaScript, mobile app bundles, or public repositories. Rotate your keys immediately if you suspect they've been compromised.
</Warning>

## Public key

The public key is deliberately restricted — it can **only** call `POST /v1/checkout/initialize`, and requires an extra header identifying your business:

```http theme={null}
Authorization: Bearer pk_live_YOUR_PUBLIC_KEY
X-Business-ID: biz_your_business_id
```

This is what the [JavaScript widget](/sdks/javascript) and mobile SDKs use, since it's safe to ship in code a customer's device can inspect — it can't be used to list your transactions, create virtual accounts, or do anything beyond starting a single checkout.

Any other endpoint called with a public key returns:

```json theme={null}
{ "status": false, "message": "Public key authentication is only permitted for checkout initialization." }
```

## Live vs test mode

Every key comes in a live and test pair. Payracle detects which mode you're in automatically from which literal key you send — there's no separate mode flag to set. Test mode calls never move real money:

* Virtual accounts and checkouts created with `sk_test_...` / `pk_test_...` generate fake sandbox account numbers instead of calling SafeHaven/Paga/PalmPay.
* Sandbox checkouts can be marked paid via `POST /v1/checkout/sandbox/simulate` — see [Checkout & Dynamic Accounts](/checkout/overview).

## IP whitelisting

Optionally restrict a secret key to specific IPs from **Developer › API Keys**. Requests from any other IP get:

```json theme={null}
{ "status": false, "message": "Request IP is not whitelisted." }
```