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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# API Authentication - Bearer Tokens and API Key Scoping

> Generate, scope, rotate, and use OwnPay API keys with Bearer token authentication across the Merchant, Admin, and Mobile REST APIs.

OwnPay uses API keys for authentication. All API requests must include a valid API key.

## API key format

```text theme={null}
op_live_abc123xyz...
op_secret_def456...
```

* **Public Key** (`op_live_...`) - Used in client-side code
* **Secret Key** (`op_secret_...`) - Used for server-side authentication

## Generating keys

1. Log in to OwnPay admin
2. Go to **Developers > API Keys**
3. Click **Generate API Key**
4. Choose access level (Full Access or Read-Only)
5. Copy both keys immediately

<Warning>
  Keys are shown once only. Store them in environment variables, never in code.
</Warning>

## Using keys

### HTTP Header

```bash theme={null}
curl -H "Authorization: Bearer op_live_your_key" \
     https://yourdomain.com/api/v1/payments
```

### PHP SDK

```php theme={null}
$client = new Client(
    publicKey: $_ENV['OWNPAY_PUBLIC_KEY'],
    secretKey: $_ENV['OWNPAY_SECRET_KEY'],
    baseUrl: 'https://yourdomain.com/api/v1'
);
```

### Node.js SDK

```javascript theme={null}
const ownpay = new OwnPay({
  publicKey: process.env.OWNPAY_PUBLIC_KEY,
  secretKey: process.env.OWNPAY_SECRET_KEY,
  baseUrl: 'https://yourdomain.com/api/v1'
});
```

## Key security

* Never commit keys to git repositories
* Use environment variables for storage
* Rotate keys every 90 days
* Use separate keys per application
* Monitor API usage for anomalies
* Revoke unused keys immediately

## Key rotation

1. Generate a new key pair
2. Update all applications to use the new key
3. Test in production
4. Delete the old key
5. Verify no errors

## Error codes

| Error                      | Cause                           |
| -------------------------- | ------------------------------- |
| `invalid_api_key`          | Key not found or malformed      |
| `expired_api_key`          | Key has expired                 |
| `revoked_api_key`          | Key has been revoked            |
| `insufficient_permissions` | Key lacks required access level |


## Related topics

- [OwnPay API Overview - REST API for Multi-Brand Payments](/docs/api/overview.md)
- [Refresh Access Token](/docs/api-reference/refresh-access-token.md)
- [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md)
- [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md)
- [Pair Mobile Companion Device](/docs/api-reference/pair-mobile-companion-device.md)