API Authentication

OwnPay authenticates every API request via a Bearer token in the Authorization header. You generate API keys from the admin panel - see API keys for the full key management guide.

How to get an API key

Log in to your OwnPay admin panel
Navigate to Developers → API Keys
Click Generate API Key
Choose the access scope (read, write, or admin)
Copy the key immediately - it is shown only once

Store API keys in environment variables. Never commit them to version control.

Header format

Every API request must include the key as a Bearer token:

Authorization: Bearer op_live_abc123.def456

The key prefix op_live_ identifies a live key. Test-mode keys use the op_test_ prefix.

Key scopes

API keys carry one of three scopes, which determine which endpoints the key can access:

Scope	Can read	Can write	Can manage	Typical use
`read`	Yes	No	No	Dashboards, reporting bots
`write`	Yes	Yes	No	Payment creation, checkout flows
`admin`	Yes	Yes	Yes	Full platform management

The scope is set when you generate the key and cannot be changed afterward. Create separate keys for separate applications.

Super admin operations

A small set of platform-level operations (creating brands, managing system users) require an additional header on top of an admin-scoped key:

Authorization: Bearer op_live_abc123.def456
X-Super-Admin-Email: [email protected]

Only the super admin email registered during installation can use this header. Without it, admin-scoped endpoints return a 403.

Authentication error response

If the key is missing, invalid, expired, or lacks the required scope, the API returns:

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Common auth error codes:

Code	HTTP status	Meaning
`invalid_api_key`	401	Key not found or malformed
`expired_api_key`	401	Key has passed its expiration date
`revoked_api_key`	401	Key was manually revoked
`insufficient_permissions`	403	Key scope too low for this endpoint

Code examples

curl -X GET https://your-domain.com/api/v1/payments/pay_abc123 \
  -H "Authorization: Bearer op_live_abc123.def456"

$ch = curl_init('https://your-domain.com/api/v1/payments/pay_abc123');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $_ENV['OWNPAY_API_KEY'],
        'Content-Type: application/json',
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-domain.com/api/v1/payments/pay_abc123', {
  headers: {
    'Authorization': `Bearer ${process.env.OWNPAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

import os
import requests

resp = requests.get(
    'https://your-domain.com/api/v1/payments/pay_abc123',
    headers={
        'Authorization': f'Bearer {os.environ["OWNPAY_API_KEY"]}',
        'Content-Type': 'application/json',
    },
)
data = resp.json()

Best practices

Rotate keys every 90 days
Use one key per environment (dev, staging, prod)
Use one key per application
Monitor usage in Developers → API Keys for anomalies
Revoke unused keys immediately

Overview

Merchant API

Mobile API

Admin API

API Authentication

How to get an API key

Header format

Key scopes

Super admin operations

Authentication error response

Code examples

Best practices

​How to get an API key

​Header format

​Key scopes

​Super admin operations

​Authentication error response

​Code examples

​Best practices

​Related pages

How to get an API key

Header format

Key scopes

Super admin operations

Authentication error response

Code examples

Best practices

Related pages