Skip to main content

Authentication

All Lightning Enable API requests require authentication using an API key.

API Key Types​

TypeHeaderPurpose
Merchant API KeyX-API-KeyPayment operations
Admin API KeyX-API-KeyMerchant management

Using Your API Key​

Include your API key in the X-API-Key header:

curl -X GET https://api.lightningenable.com/api/payments/inv_123 \
  -H "X-API-Key: le_merchant_abc123xyz..."

API Key Format​

Lightning Enable API keys follow this format:

le_merchant_<random-characters>

Example:

le_merchant_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Obtaining API Keys​

Via Subscription Signup​

When you subscribe to Lightning Enable:

  1. Complete the checkout process
  2. Your API key is displayed on the success page
  3. API key is also emailed to you

Via Admin API (Enterprise)​

Administrators can generate API keys:

curl -X POST https://api.lightningenable.com/api/admin/merchants \
  -H "X-API-Key: admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Merchant",
    "email": "merchant@example.com"
  }'

Response includes the generated API key:

{
  "id": 123,
  "name": "New Merchant",
  "apiKey": "le_merchant_abc123..."
}

API Key Security​

Best Practices​

  1. Never commit API keys to version control
# .gitignore
.env
appsettings.Development.json
  1. Use environment variables
export LIGHTNING_API_KEY="le_merchant_abc123..."
const apiKey = process.env.LIGHTNING_API_KEY;
  1. Rotate keys periodically

Request a new key and update your configuration.

  1. Use separate keys for development and production

Keep your production key secret by using testnet keys during development.

Storage Recommendations​

EnvironmentRecommendation
Development.env file (gitignored)
CI/CDSecret management (GitHub Secrets, etc.)
ProductionEnvironment variables or secret manager

Key Rotation​

Regenerate API Key​

Request a new API key when:

  • Key may have been compromised
  • Employee with access leaves
  • Periodic security rotation
curl -X POST https://api.lightningenable.com/api/admin/merchants/{id}/regenerate-key \
  -H "X-API-Key: admin-api-key"

Response:

{
  "id": 123,
  "apiKey": "le_merchant_newkey123...",
  "previousKeyInvalidated": true
}
warning

The old API key is immediately invalidated. Update your applications before regenerating.

Error Responses​

Missing API Key​

HTTP/1.1 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "API key is required. Include X-API-Key header."
}

Invalid API Key​

HTTP/1.1 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Inactive Merchant​

HTTP/1.1 403 Forbidden

{
  "error": "Forbidden",
  "message": "Merchant account is inactive"
}

Testing Authentication​

Verify your API key works:

curl -X GET https://api.lightningenable.com/health \
  -H "X-API-Key: le_merchant_abc123..."

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-12-29T12:00:00Z"
}

Code Examples​

JavaScript​

const API_KEY = process.env.LIGHTNING_API_KEY;

async function makeRequest(endpoint) {
  const response = await fetch(`https://api.lightningenable.com${endpoint}`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });

  if (response.status === 401) {
    throw new Error('Invalid API key');
  }

  return response.json();
}

C# / .NET​

public class LightningEnableClient
{
    private readonly HttpClient _client;

    public LightningEnableClient(IConfiguration config)
    {
        _client = new HttpClient
        {
            BaseAddress = new Uri("https://api.lightningenable.com")
        };
        _client.DefaultRequestHeaders.Add("X-API-Key", config["LightningApiKey"]);
    }

    public async Task<T> GetAsync<T>(string endpoint)
    {
        var response = await _client.GetAsync(endpoint);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<T>();
    }
}

Python​

import os
import requests

API_KEY = os.environ.get('LIGHTNING_API_KEY')
BASE_URL = 'https://api.lightningenable.com'

def make_request(endpoint):
    response = requests.get(
        f'{BASE_URL}{endpoint}',
        headers={'X-API-Key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

Next Steps​