> ## 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 Keys: Create, Rotate, and Secure

> Manage your Okapay secret and publishable API keys. Learn how to create keys, use them in requests, rotate them, and keep them secure.

Okapay uses API keys to authenticate every request you make to the Merchant API. You have two types of key — a secret key for server-side calls and a publishable key for client-side checkout flows. This page explains the difference, how to create and manage your keys, and how to keep them secure.

## Key types

> [card] Secret Key
>
> Prefixed `sk_live_`. Grants full server-side access to all API resources — products, checkout sessions, verifications, and more. **Never expose this in frontend code.**

> [card] Publishable Key
>
> Safe to include in browser JavaScript and mobile apps. Scoped to client-side checkout operations only and does not grant access to server-side resources.

## Finding your API keys

Log in to the [Okapay dashboard](https://dashboard.okapay.net/dashboard/api-keys) and navigate to **Dashboard → API Keys**. Both keys are displayed on this page alongside your Merchant ID.

## Using your secret key in API requests

Pass your secret key as a Bearer token in the `Authorization` header of every server-side 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 that creates 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 #1042",
    "source": "custom_php"
  }'
```

## Setting up your secret key as an environment variable

Store your secret key in an environment variable rather than hard-coding it in source files. The Okapay PHP SDK reads this variable automatically.

Add the following to your `.env` file:

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

> [!WARNING]
>
> Never commit your `.env` file to version control. Add it to `.gitignore` immediately and check that it has not already been committed before pushing to a remote repository.

## Using your secret key with the PHP SDK

Once `OKAPAY_SECRET_KEY` is set in your environment, create the client without any arguments:

```php theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Okapay\Client;

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

You can also pass the key explicitly if you prefer:

```php theme={null}
$okapay = new Client(['secret_key' => 'sk_live_xxxxxxxxx']);
```

In a Laravel application, register the key in `config/services.php`:

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

Then pass the config array to the client:

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

## Rotating your API keys

Rotate your secret key immediately if you suspect it has been compromised, or as part of a scheduled security review.

**1. Open the API Keys page**

Log in to [dashboard.okapay.net/dashboard/api-keys](https://dashboard.okapay.net/dashboard/api-keys).

**2. Generate a new secret key**

Click **Generate new key**. Your new `sk_live_` key is displayed once — copy it immediately because it will not be shown again.

**3. Update all environments**

Replace the old key with the new one in every environment where it is used: local development, staging, and production. Update your hosting provider's secret management, CI/CD environment variables, and any other locations where the key is stored.

**4. Revoke the old key**

Once all environments are updated and verified, revoke the old key from the dashboard. Requests using the revoked key will immediately return `401 Unauthorized`.

> [!NOTE]
>
> There is no grace period after revoking a key. Make sure all environments are updated before you revoke the old key to avoid service disruption.

## Security rules

Follow these practices to keep your keys and account secure:

* **Use environment variables** — store `OKAPAY_SECRET_KEY` in `.env` locally and your hosting provider's secret manager in production. Never hard-code key values in source files.
* **Keep `.env` out of version control** — add `.env` to `.gitignore` and audit your repository history if you are unsure whether a key was previously committed.
* **Use the publishable key for client-side code** — never use your secret key in browser JavaScript, mobile apps, or any code that runs on a customer's device.
* **Limit access** — only the server processes and team members that genuinely need the secret key should have access to it.
* **Rotate on suspicion** — if you see unexpected API activity or believe the key may have been exposed, rotate it immediately.

## Authentication errors

| HTTP Status | Meaning | Resolution |
| - | - | - |
| `401 Unauthorized` | Missing, malformed, or revoked API key | Confirm the `Authorization: Bearer sk_live_...` header is present and the key has not been revoked |
| `403 Forbidden` | Key lacks permission for the resource | Ensure you are using your secret key (not publishable key) for server-side endpoints |


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