OpenNode API Keys

API keys authenticate your requests to OpenNode through Lightning Enable. This guide shows how to generate, configure, and secure your API keys.

API Key Types

OpenNode provides different API key types:

Key Type	Permissions	Use Case
Invoice	Create invoices, check status	Payment creation
Withdrawal	Send payments, refunds	Refund processing
Admin	Full account access	Account management

warning

Lightning Enable requires an Invoice key for basic payments, or an Admin key if you need refund capabilities.

Generate API Key

Development Environment

1. Log in to app.dev.opennode.com
2. Navigate to Integrations > API Keys
3. Click Generate New Key
4. Select key type:
   • Invoice for payment creation
   • Admin for full access (including refunds)
5. Copy and securely store the key

Production Environment

1. Log in to app.opennode.com
2. Navigate to Integrations > API Keys
3. Click Generate New Key
4. Select key type
5. Copy and securely store the key

danger

API keys are shown only once. If you lose it, you'll need to generate a new one.

Configure in Lightning Enable

Via Admin API

Add your OpenNode API key to your merchant account:

curl -X PUT https://api.lightningenable.com/api/admin/merchants/{merchantId} \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "openNodeApiKey": "your-opennode-api-key"
  }'

Via Environment Variables

For self-hosted deployments:

# .env file
OPENNODE_API_KEY=your-opennode-api-key
OPENNODE_ENVIRONMENT=dev  # or "production"

Via Configuration File

{
  "OpenNode": {
    "ApiKey": "your-opennode-api-key",
    "Environment": "dev"
  }
}

API Key Security

Environment Variables

Never hardcode API keys. Use environment variables:

// Good
const apiKey = process.env.OPENNODE_API_KEY;

// Bad - Never do this
const apiKey = "abc123-your-actual-key";

Git Ignore

Ensure sensitive files are not committed:

# .gitignore
.env
.env.local
.env.production
appsettings.Development.json

Secret Managers

For production, use a secret manager:

Azure Key Vault:

az keyvault secret set \
  --vault-name your-vault \
  --name OpenNodeApiKey \
  --value "your-api-key"

AWS Secrets Manager:

aws secretsmanager create-secret \
  --name OpenNodeApiKey \
  --secret-string "your-api-key"

HashiCorp Vault:

vault kv put secret/opennode api_key="your-api-key"

Key Rotation

Regularly rotate API keys for security:

When to Rotate

• Every 90 days (recommended)
• After employee departure
• If key may be compromised
• After security incident

Rotation Process

1. Generate new key in OpenNode dashboard
2. Update configuration with new key
3. Deploy changes to all environments
4. Verify functionality with test payment
5. Revoke old key in OpenNode dashboard

Zero-Downtime Rotation

For production systems:

// Support multiple keys during rotation
const OPENNODE_KEYS = [
  process.env.OPENNODE_API_KEY_NEW,
  process.env.OPENNODE_API_KEY_OLD
];

async function createInvoice(data) {
  for (const key of OPENNODE_KEYS) {
    try {
      return await openNode.createCharge(data, key);
    } catch (error) {
      if (error.status !== 401) throw error;
      // Try next key
    }
  }
  throw new Error('All API keys failed');
}

Verify API Key

Test your API key is working:

Using cURL

# Development
curl -X GET https://dev-api.opennode.com/v1/account/balance \
  -H "Authorization: your-api-key"

# Production
curl -X GET https://api.opennode.com/v1/account/balance \
  -H "Authorization: your-api-key"

Expected Response

{
  "data": {
    "balance": {
      "BTC": "0.00123456",
      "USD": "52.34"
    }
  }
}

Error Response (Invalid Key)

{
  "success": false,
  "message": "Invalid API key"
}

API Key Permissions

Invoice Key Capabilities

• Create Lightning invoices
• Check invoice status
• List transactions
• Get exchange rates

Admin Key Capabilities

Everything in Invoice key, plus:

• Create withdrawals
• Process refunds
• Manage webhooks
• Access account settings

Minimal Permissions

Use the least privileged key for your use case:

Feature	Required Key
Accept payments	Invoice
Check payment status	Invoice
Process refunds	Admin
Send payments	Admin

Troubleshooting

Invalid API Key

{
  "error": "Invalid API key"
}

Solutions:

1. Verify key is copied correctly (no extra spaces)
2. Confirm environment matches (dev vs production)
3. Check key hasn't been revoked
4. Generate new key if needed

Permission Denied

{
  "error": "Insufficient permissions"
}

Solutions:

1. Check key type (Invoice vs Admin)
2. Generate key with appropriate permissions
3. Verify account is fully verified

Key Not Found

{
  "error": "API key required"
}

Solutions:

1. Check Authorization header format
2. Verify environment variable is set
3. Confirm key is passed to API calls

Best Practices Checklist

• Use environment variables for all API keys
• Add sensitive files to .gitignore
• Use secret manager in production
• Enable 2FA on OpenNode account
• Use Invoice key for payments (minimal permissions)
• Use Admin key only when refunds needed
• Rotate keys every 90 days
• Different keys for dev and production
• Monitor for unauthorized usage
• Document key locations for team

Next Steps

• Webhooks - Configure payment notifications
• Testing - Test your integration
• Quick Start - Make your first payment