Skip to main content

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 TypePermissionsUse Case
InvoiceCreate invoices, check statusPayment creation
WithdrawalSend payments, refundsRefund processing
AdminFull account accessAccount 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​

note

Dev-environment keys are useful for exploring OpenNode's own API on testnet, but they cannot be used with Lightning Enable's hosted platform, which connects to OpenNode production. Use a production key below when configuring Lightning Enable.

  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 Dashboard​

Sign in to your Lightning Enable dashboard and navigate to Settings → Payment Provider to paste your OpenNode API key.

Via Merchant API​

curl -X PUT https://api.lightningenable.com/api/merchant/opennode-key \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-opennode-api-key"
  }'
These are the only two configuration methods

Your OpenNode key is stored by Lightning Enable's hosted platform, encrypted at rest with AES-256-GCM. There is no environment variable or configuration file to set — the dashboard and the PUT /api/merchant/opennode-key endpoint above are the only ways to configure it.

Production keys only

The hosted platform connects to OpenNode's production API, so configure a production OpenNode key (from app.opennode.com). Development-environment keys will fail validation.

API Key Security​

  • Never commit your OpenNode key to source control or paste it into client-side code — the only place it belongs is the Lightning Enable dashboard or the PUT /api/merchant/opennode-key call.
  • If you keep a copy, store it in a password manager or secret store.
  • Lightning Enable never returns your OpenNode key back out of the API once saved.
  • If you suspect the key leaked, revoke it in the OpenNode dashboard immediately and configure a new one.

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 the OpenNode dashboard
  2. Update the key in Lightning Enable — dashboard (Settings → Payment Provider) or: 
    curl -X PUT https://api.lightningenable.com/api/merchant/opennode-key \
      -H "X-API-Key: your-merchant-api-key" \
      -H "Content-Type: application/json" \
      -d '{ "apiKey": "your-new-opennode-api-key" }'
  3. Validate the new key: 
    curl -X POST https://api.lightningenable.com/api/merchant/validate-opennode \
      -H "X-API-Key: your-merchant-api-key"
  4. Verify functionality with a small test payment
  5. Revoke the old key in the OpenNode dashboard

The update takes effect immediately — subsequent payments use the new key, so there is no downtime window to manage.

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:

FeatureRequired Key
Accept paymentsInvoice
Check payment statusInvoice
Process refundsAdmin
Send paymentsAdmin

Troubleshooting​

Invalid API Key​

{
  "error": "Invalid API key"
}

Solutions:

  1. Verify key is copied correctly (no extra spaces)
  2. Confirm it is a production key from app.opennode.com — the hosted platform does not use OpenNode's dev environment
  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 the Authorization header format
  2. Verify a key is saved in Lightning Enable (the dashboard, or GET /api/merchant/me — check hasOpenNodeKey)
  3. Re-save the key via the dashboard or PUT /api/merchant/opennode-key

Best Practices Checklist​

  • Configure the key only via the Lightning Enable dashboard or PUT /api/merchant/opennode-key
  • Keep any copy in a password manager or secret store, never in source control
  • Enable 2FA on OpenNode account
  • Use Invoice key for payments (minimal permissions)
  • Use Admin key only when refunds needed
  • Rotate keys every 90 days
  • Monitor for unauthorized usage

Next Steps​