API Authentication

Secure your Pelago API integration with proper authentication.

API Keys

Pelago uses a dual-key authentication system:

Key Type	Purpose	Example
Public Key	Identifies your account	pk_live_xxxxx
Secret Key	Signs requests	sk_live_xxxxx

Getting Your Keys

1. Log into the Pelago Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key Pair
4. Store the secret key securely (shown only once)

Environment Keys

Environment	Key Prefix	Purpose
Sandbox	pk_test_ / sk_test_	Development & testing
Production	pk_live_ / sk_live_	Live transactions

Authentication Methods

Header Authentication (Recommended)

curl -X POST https://api.pelago.tech/v1/payments \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "USD"}'

SDK Authentication

JavaScript:

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY,      // pk_live_xxxxx
  apiSecret: process.env.PELAGO_API_SECRET, // sk_live_xxxxx
  environment: 'production'
});

Python:

from pelago import PelagoClient
import os

pelago = PelagoClient(
    api_key=os.environ['PELAGO_API_KEY'],
    api_secret=os.environ['PELAGO_API_SECRET'],
    environment='production'
)

Go:

import "github.com/polyflow/pelago-go"

client := pelago.NewClient(pelago.Config{
    APIKey:      os.Getenv("PELAGO_API_KEY"),
    APISecret:   os.Getenv("PELAGO_API_SECRET"),
    Environment: pelago.Production,
})

Request Signing

For enhanced security, sign your requests:

import crypto from 'crypto';

function createSignedRequest(
  method: string,
  path: string,
  body: object,
  apiSecret: string
) {
  const timestamp = Date.now();
  const payload = `${timestamp}.${method}.${path}.${JSON.stringify(body)}`;
  
  const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(payload)
    .digest('hex');
  
  return {
    'X-Pelago-Timestamp': timestamp.toString(),
    'X-Pelago-Signature': signature
  };
}

// Usage
const body = { amount: 100, currency: 'USD' };
const signatureHeaders = createSignedRequest(
  'POST',
  '/v1/payments',
  body,
  apiSecret
);

fetch('https://api.pelago.tech/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Api-Secret': apiSecret,
    'Content-Type': 'application/json',
    ...signatureHeaders
  },
  body: JSON.stringify(body)
});

Key Security Best Practices

DO ✅

• Store keys in environment variables
• Use different keys for sandbox/production
• Rotate keys every 90 days
• Restrict key permissions if possible

DON'T ❌

• Commit keys to version control
• Share keys via insecure channels
• Use production keys in development
• Expose keys in client-side code

Key Rotation

Rotate your API keys regularly:

// 1. Generate new keys in dashboard
// 2. Update your environment variables
// 3. Verify new keys work
const test = await pelago.payments.list({ limit: 1 });

// 4. Delete old keys from dashboard

Scoped Keys (Enterprise)

For enterprise accounts, create scoped keys with limited permissions:

Scope	Permissions
payments:read	View payments only
payments:write	Create & manage payments
settlements:read	View settlements
refunds:write	Process refunds

// Scoped key example
const pelago = new PelagoClient({
  apiKey: 'pk_live_xxxxx_scoped',
  apiSecret: 'sk_live_xxxxx',
  environment: 'production'
});

// This key can only read payments
await pelago.payments.list(); // ✓ Works
await pelago.payments.create({...}); // ✗ Forbidden

Troubleshooting

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid/missing keys	Check key values
403 Forbidden	Key lacks permission	Use correct scope
429 Too Many Requests	Rate limited	Reduce request rate

Next Steps

• Create Payments
• Configure Webhooks
• Error Handling