API Request Authentication

Authentication MethodCopied!

All API requests require authentication using the following HTTP headers:

x-client-key: your_api_key_here
x-client-secret: your_api_secret_here

Getting Your API CredentialsCopied!

1. Login to your console account to create an API key for your application

2. Generate Your Credentials: You'll generate both a Client Key and Client Secret

3. Store Securely: Keep these credentials secure and never expose them in client-side code

Required HeadersCopied!

Authentication Headers

• x-client-key: Your API key identifier (64-character hex string)

• x-client-secret: Your API secret (128-character hex string)

Example Authentication Headers

x-client-key: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
x-client-secret: 9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef
Content-Type: application/json

Scope-Based Access ControlCopied!

API keys are configured with specific scopes that determine which operations you can perform. Common scopes include:

Resource Scopes

• Payment Links: payment_link:create, payment_link:read, payment_link:update, payment_link:list

• Invoices: invoice:create, invoice:read, invoice:update, invoice:list

• Customers: customer:create, customer:read, customer:update, customer:list

• Products: product:create, product:read, product:update, product:list

• Payments: payment:create, payment:read, payment:update, payment:list

• Webhooks: webhook:create, webhook:read, webhook:update, webhook:delete, webhook:list

Complete Request ExampleCopied!

// JavaScript/Node.js Example
const axios = require('axios');

const apiRequest = async () => {
  try {
    const response = await axios.post('https://api.example.com/v0/payment-links', {
      name: "Test Payment Link",
      amount: 1000,
      currency: "USD"
    }, {
      headers: {
        'x-client-key': process.env.API_CLIENT_KEY,
        'x-client-secret': process.env.API_CLIENT_SECRET,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data);
    throw error;
  }
};

# Python Example
import requests
import os

def make_api_request():
    headers = {
        'x-client-key': os.getenv('API_CLIENT_KEY'),
        'x-client-secret': os.getenv('API_CLIENT_SECRET'),
        'Content-Type': 'application/json'
    }
    
    data = {
        'name': 'Test Payment Link',
        'amount': 1000,
        'currency': 'USD'
    }
    
    response = requests.post(
        'https://api.example.com/v0/payment-links',
        json=data,
        headers=headers
    )
    
    if response.status_code == 401:
        raise Exception('Authentication failed - check your API credentials')
    elif response.status_code == 403:
        raise Exception('Access denied - insufficient permissions')
    
    return response.json()

# cURL Example
curl -X POST "https://api.example.com/v0/payment-links" \
  -H "x-client-key: your_api_key_here" \
  -H "x-client-secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Payment Link",
    "amount": 1000,
    "currency": "USD"
  }'

Error ResponsesCopied!

Missing Authentication

{
  "statusCode": 401,
  "message": "Client key or secret missing",
  "code": "UNAUTHENTICATED"
}

Invalid Credentials

{
  "statusCode": 401,
  "message": "Invalid client app credentials",
  "code": "UNAUTHENTICATED"
}

API Key Not Found

{
  "statusCode": 403,
  "message": "API key not found",
  "code": "UNAUTHENTICATED"
}

Inactive API Key

{
  "statusCode": 403,
  "message": "API key is inactive",
  "code": "UNAUTHENTICATED"
}

Insufficient Permissions

{
  "statusCode": 403,
  "message": "Missing required scope",
  "error": "Forbidden",
  "details": "API key does not have the required payment_link:create scope"
}

Security Best PracticesCopied!

1. Secure Storage

• Never hardcode API credentials in your source code

• Use environment variables or secure configuration management

• Store credentials in encrypted form when possible

2. Environment Separation

• Use different API keys for development and production environments

• Keep staging and production credentials completely separate

3. Network Security

• Always use HTTPS for API requests

• Implement proper certificate validation

• Consider IP whitelisting for additional security

4. Access Management

• Regularly rotate your API credentials

• Monitor usage and review access logs

• Revoke unused or compromised keys immediately

5. Error Handling

• Never log API credentials in error messages

• Implement proper retry logic for temporary failures

• Mask sensitive data in logs and debugging output

Testing Your AuthenticationCopied!

Use our health check endpoint to verify your authentication setup:

curl -X GET "https://api.example.com/v0/health" \
  -H "x-client-key: your_api_key_here" \
  -H "x-client-secret: your_api_secret_here"

Success Response:

{
  "status": "ok",
  "timestamp": "2024-03-20T12:00:00.000Z",
  "version": "1.0.0",
  "database": "connected",
  "message": "Service is up and running",
  "authenticated": true
}

Additional Security FeaturesCopied!

IP Whitelisting

Your API key may be configured with IP restrictions. On the console you can:

• Add new IP addresses to your whitelist

• Update your IP restrictions

• Configure domain-based access controls

Monitoring & Alerts

• All API requests are logged and monitored

• Unusual activity patterns are flagged for review

• Failed authentication attempts are tracked