Skip to main content

Authentication

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

API Key​

Lightning Enable uses a single merchant API key for payment operations and merchant self-service endpoints. Include it in the X-API-Key header on every authenticated request.

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: YOUR_API_KEY"

API Key Format​

Treat your API key as an opaque string. Do not validate, parse, or pattern-match it in your code — store it exactly as issued and send it back verbatim.

For reference, keys issued at signup start with an lgw_ prefix followed by random characters, while keys issued on regeneration are unprefixed random strings (roughly 44 characters of base64, which may include +, /, and =). Both are equally valid; the server treats every key the same way. The format may change — code that assumes a specific prefix or length will break.

Obtaining Your API Key​

When you subscribe to Lightning Enable:

  1. Complete the checkout process
  2. Your API key is displayed on the success page
  3. You can view it (or regenerate it) any time at Dashboard → Settings (/dashboard/settings)

Enterprise customers needing multiple keys or custom onboarding should contact support@lightningenable.com.

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="YOUR_API_KEY"
const apiKey = process.env.LIGHTNING_API_KEY;
  1. Rotate keys periodically

Regenerate your key from the dashboard 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 your API key when:

  • Key may have been compromised
  • Employee with access leaves
  • Periodic security rotation

Rotate via the Lightning Enable dashboard (Dashboard → Settings → API Key → Regenerate, at /dashboard/settings) or via POST /api/merchant/regenerate-key. The old API key is immediately invalidated on regeneration — update your applications before rotating.

Error Responses​

Missing API Key​

HTTP/1.1 401 Unauthorized

{
  "error": "API key required",
  "message": "Please provide API key in X-API-Key header"
}

Invalid API Key​

HTTP/1.1 401 Unauthorized

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or inactive"
}

This is also what you receive if your merchant account has been deactivated — an inactive account's key no longer matches any active merchant. Requests that authenticate successfully but hit subscription or feature gates return 403 responses instead; see the Error Reference.

Failed-Authentication Throttling​

Failed authentication attempts are throttled per IP address: more than 20 failures (missing or invalid API key) within a 60-second fixed window blocks further authenticated requests from that IP until the window expires.

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": "Too many failed authentication attempts",
  "message": "Slow down and try again in 42 seconds"
}

If you see this response, your integration is repeatedly sending a wrong or stale key — fix the key, don't retry. Retrying with the same bad key records more failures and keeps the block engaged. Verify your key at Dashboard → Settings, then wait out the Retry-After seconds before the next attempt.

This throttle is distinct from the general request rate limiter (whose 429 body says "Too many requests" and carries a retryAfter field in the JSON body instead of a Retry-After header). See Rate Limiting for the comparison.

Testing Authentication​

First, verify the API is running by calling the public health endpoint (no authentication required):

curl https://api.lightningenable.com/health

Expected response:

{
  "status": "Healthy",
  "totalDuration": 42.15,
  "checks": [
    {
      "name": "database",
      "status": "Healthy",
      "duration": 38.72,
      "description": null,
      "exception": null,
      "tags": ["db", "sql"]
    }
  ]
}

Then verify your API key works by calling an authenticated endpoint:

curl -X GET https://api.lightningenable.com/api/merchant/me \
  -H "X-API-Key: YOUR_API_KEY"

A 200 response confirms your key is valid. A 401 means the key is invalid or missing.

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​