API Keys

API keys provide a secure way to authenticate server-to-server requests to the OrcaRail API.

Overview

API keys consist of two parts:

Key (ak_live_...) - Public identifier
Secret (sk_live_...) - Private secret (keep secure!)

Both are required for authentication using Basic Auth.

Creating API Keys in the Dashboard

The easiest way to create and manage API keys is from the OrcaRail Dashboard:

Sign in — Open Dashboard → Sign in and enter your credentials.
Create your first organization if prompted — New accounts must create an organization before they can continue in the dashboard. Guided setup shows the generated slug and lets you edit it before creation if needed.
Complete the required guided-setup steps — OrcaRail keeps the dashboard locked until your organization has a selling mode, at least one product, at least one price, one API key, and one widget.
Create API key — Guided setup includes an inline API key step, or you can open Dashboard → API Keys from the sidebar.
Copy key and secret — Copy the key and secret immediately; the secret is shown only once and cannot be retrieved later.

You can also list, update, and revoke API keys on the same Dashboard page.

You can set a commission percent (0–100) on an API key. When payments are created with that key:

The commission is calculated on the quote and shown to the payer at checkout.
The commission amount is stored on the quote and included in totals.
On withdrawal, the commission is sent to your account’s withdrawal settings address (the same strategy and address used for your main payouts).

Use this to split revenue with partners or earn a share on every payment made through your integration.

Creating API Keys via API

Via API

Create an API key using the API Keys endpoint:

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Request Body:

{
  "name": "Production API Key",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "commissionPercent": 4
}

The created key is scoped to the organization identified by :organizationId. The bearer token must belong to a user or session that is authorized to manage that exact organization; the path parameter is required and must match the organization you intend to manage.

commissionPercent (optional): number 0–100. When set, this percentage is applied to payments created with this key; the amount is shown to the payer and sent to your withdrawal address.

Response:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning Important The secret is only shown once when the API key is created. Save it immediately! If you lose it, you'll need to create a new API key. :::

Example: Creating an API Key

const response = await fetch(
  'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production API Key',
    }),
  }
)

const { apiKey, key, secret } = await response.json()

// IMPORTANT: Save the secret securely!
console.log('API Key:', key)
console.log('API Secret:', secret) // Only shown once!

Using API Keys

Basic Authentication

API keys use HTTP Basic Authentication. The format is:

Authorization: Basic base64(key:secret)

cURL Example

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012 \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

JavaScript Example

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'

// Create base64 encoded credentials
const credentials = btoa(`${key}:${secret}`)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
    }),
  }
)

Node.js Example

const https = require('https')

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'
const credentials = Buffer.from(`${key}:${secret}`).toString('base64')

const options = {
  hostname: 'api.orcarail.com',
  path: '/api/v1/payment_intents',
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
}

const req = https.request(options, (res) => {
  // Handle response
})

req.write(
  JSON.stringify({
    amount: '100.00',
    currency: 'usd',
    payment_method_types: ['crypto'],
    tokenId: 1,
    networkId: 1,
    return_url: 'https://merchant.example.com/return',
  })
)

req.end()

Python Example

import requests
import base64

key = 'ak_live_abc123def456'
secret = 'sk_live_xyz789uvw012'

# Create base64 encoded credentials
credentials = base64.b64encode(f'{key}:{secret}'.encode()).decode()

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
    },
)

Managing API Keys

You can list, update, and revoke API keys from Dashboard → API Keys, or use the API as below.

List Your API Keys

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

Response:

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Update an API Key

Update an API key's name or webhook URL:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Request Body:

{
  "name": "Updated API Key Name",
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

Response:

{
  "id": 1,
  "name": "Updated API Key Name",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

To remove a webhook URL, set it to null:

{
  "webhookUrl": null
}

Revoke an API Key

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

Response:

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "revoked",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Security Best Practices

1. Keep Secrets Secure

Never commit API keys to version control
Store secrets in environment variables or secret management systems
Use different keys for different environments (development, staging, production)

2. Rotate Keys Regularly

Create new API keys periodically
Revoke old keys after creating new ones
Update your applications to use the new keys

3. Use Descriptive Names

Give your API keys descriptive names to track their usage:

{
  "name": "Production - Payment Service"
}

4. Limit Key Scope

Create separate API keys for different services or environments:

Production - Web Server
Production - Background Jobs
Staging - Testing
Development - Local

5. Monitor Key Usage

Regularly review your API keys and revoke any that are no longer needed.

Testing API Keys

You can test if your API key is valid:

POST /api/v1/api-keys/test

Request Body:

{
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

Response:

{
  "ok": true
}

Error Responses

Invalid Credentials

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Missing Authorization Header

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Webhook Configuration

API keys can have an optional webhookUrl that receives payment events. When a payment event occurs, OrcaRail will send a webhook to the configured URL.

See Webhook Configuration for detailed instructions on setting up webhooks.

Next Steps

Webhook Configuration - Configure webhooks for your API keys
Bearer Tokens - Learn about JWT authentication
Getting Started - Create your first payment

Overview​

Creating API Keys in the Dashboard​

Commission (split and get your share)​

Creating API Keys via API​

Via API​

Example: Creating an API Key​

Using API Keys​

Basic Authentication​

cURL Example​

JavaScript Example​

Node.js Example​

Python Example​

Managing API Keys​

List Your API Keys​

Update an API Key​

Revoke an API Key​

Security Best Practices​

1. Keep Secrets Secure​

2. Rotate Keys Regularly​

3. Use Descriptive Names​

4. Limit Key Scope​

5. Monitor Key Usage​

Testing API Keys​

Error Responses​

Invalid Credentials​

Missing Authorization Header​

Webhook Configuration​

Next Steps​

Overview

Creating API Keys in the Dashboard

Commission (split and get your share)

Creating API Keys via API

Via API

Example: Creating an API Key

Using API Keys

Basic Authentication

cURL Example

JavaScript Example

Node.js Example

Python Example

Managing API Keys

List Your API Keys

Update an API Key

Revoke an API Key

Security Best Practices

1. Keep Secrets Secure

2. Rotate Keys Regularly

3. Use Descriptive Names

4. Limit Key Scope

5. Monitor Key Usage

Testing API Keys

Error Responses

Invalid Credentials

Missing Authorization Header

Webhook Configuration

Next Steps