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

# Okapay API Authentication: Bearer Tokens and SDK Auth

> Okapay authenticates every API request with Bearer token API keys. Learn how to pass keys securely, use the PHP SDK auto-auth, and handle auth errors.

Okapay authenticates every API request using API keys passed as Bearer tokens in the `Authorization` HTTP header. There are no sessions, cookies, or OAuth flows — every request is authenticated independently using the key you provide. Your keys are scoped to your merchant account and grant access to all resources within it, so keeping them secure is essential.

## Get your API keys

Log in to the merchant dashboard and navigate to **Dashboard → API Keys** at [dashboard.okapay.net/dashboard/api-keys](https://dashboard.okapay.net/dashboard/api-keys). You will find two types of credential:

**Secret Key** (`sk_live_xxxxxxxxx`) — your secret key grants full server-side access to all API resources: creating products, opening checkout sessions, verifying payments, and more. Use this key **only on your server**. Never expose it in frontend code, browser-side JavaScript, mobile apps, or public repositories.

**Publishable Key** — your publishable key is safe to include in client-side code and is intended for browser or mobile-based checkout flows only. It does not grant access to server-side resources.

You will also find your **Merchant ID** on the same page. Some API endpoints (such as checkout session creation and verification) require your Merchant ID in the URL path alongside your secret key in the header.

## Authenticate requests

Pass your secret key as a Bearer token in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer sk_live_xxxxxxxxx
```

Here is a complete example using `curl` to list your products:

```bash theme={null}
curl https://api.okapay.net/merchant-api/products \
  -H "Authorization: Bearer sk_live_xxxxxxxxx"
```

And an example creating a checkout session (which also requires your Merchant ID in the path):

```bash theme={null}
curl -X POST https://api.okapay.net/merchant-api/{merchant_id}/checkout-sessions \
  -H "Authorization: Bearer sk_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "currency": "USD",
    "description": "Order #1001",
    "source": "custom_php"
  }'
```

## With the PHP SDK

The PHP SDK handles authentication automatically. Set your secret key as an environment variable and the SDK picks it up on initialisation — you do not need to pass it in every call.

Add your key to your `.env` file:

```env theme={null}
OKAPAY_SECRET_KEY=sk_live_xxxxxxxxx
```

Then create the client without any arguments:

```php theme={null}
use Okapay\Client;

$okapay = new Client(); // auto-reads OKAPAY_SECRET_KEY from env
```

If you prefer to pass the key explicitly (for example, in a multi-tenant setup where different merchants use different keys), you can do so directly:

```php theme={null}
use Okapay\Client;

$okapay = new Client(['secret_key' => 'sk_live_xxxxxxxxx']);
```

In Laravel, register your credentials in `config/services.php` and pass them to the client:

```php theme={null}
// config/services.php
'okapay' => [
    'base_url'   => env('OKAPAY_BASE_URL'),
    'secret_key' => env('OKAPAY_SECRET_KEY'),
],
```

```php theme={null}
$okapay = new \Okapay\Client(config('services.okapay'));
```

## Security best practices

> [!WARNING]
>
> Never expose your Secret Key in frontend code, client-side JavaScript, mobile app bundles, or public source control repositories. Anyone who obtains your secret key can make API calls on behalf of your merchant account.

Follow these practices to keep your keys secure:

* **Store keys in environment variables**, not hard-coded in source files. Use `.env` locally and your hosting provider's secret management in production.
* **Add `.env` to `.gitignore`** so it is never committed to version control.
* **Use the publishable key for client-side checkout** — it is scoped to checkout-only operations and is safe to include in browser code.
* **Rotate your secret key immediately** if you suspect it has been compromised. Generate a new key in the dashboard at [dashboard.okapay.net/dashboard/api-keys](https://dashboard.okapay.net/dashboard/api-keys) and update all server environments.
* **Restrict access** to the server processes and team members that genuinely need the secret key.

## Authentication errors

If a request fails due to an authentication problem, Okapay returns a standard HTTP error code with a JSON error body. The two most common errors are:

| HTTP Status | Error | Cause |
| - | - | - |
| `401 Unauthorized` | Missing or invalid API key | The `Authorization` header is absent, malformed, or contains a key that does not exist or has been revoked. Check that you are passing `Bearer sk_live_...` correctly. |
| `403 Forbidden` | Insufficient permissions | The API key is valid but does not have permission to access the requested resource. Ensure you are using your Secret Key (not Publishable Key) for server-side endpoints. |

> [!TIP]
>
> If you receive a `401` error after recently rotating your keys, make sure you have updated the new key value in every server environment where it is used — staging, production, and any automated deployment pipelines.


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