Skip to main content

​
Authentication

All API requests to LuxCore must be authenticated using an API key. This page explains how to obtain and use your API keys.

​
Obtaining API Keys

API keys and merchant accounts are created by the LuxCore team during onboarding. Self-registration is not available.
To obtain your API keys:
  1. Contact your LuxCore account manager
  2. Or email developers@lux-core.io
Once your account is set up, you can view your API keys in the Merchant Dashboard under Settings → API Keys.

​
API Key Types

LuxCore uses API keys to authenticate requests.

​
Key Types

Key PrefixEnvironmentDescription
qp_prod_sk_ProductionReal transactions with actual money movement
qp_test_sk_TestSimulated transactions, no real money movement
Keep your API keys secure! Never expose them in client-side code, public repositories, or browser requests.

​
Making Authenticated Requests

Include your API key in the X-API-Key header with every request: 
curl -X GET "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_prod_sk_your_api_key_here" \
  -H "Content-Type: application/json"

​
JWT Bearer Token

Some endpoints also support JWT Bearer token authentication as an alternative to API keys. 
curl -X GET "https://api.lux-core.io/api/v1/payments" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"
For merchant integrations, API keys are the recommended authentication method. JWT Bearer tokens are available for advanced use cases — contact support for details.

​
Test Mode vs Production

Test and production requests use the same API endpoint. The environment is determined by your API key type.

​
Test Mode Behavior

When using test API keys (qp_test_sk_*):
  • Payments are simulated and do not process real funds
  • Webhooks are delivered normally for testing integrations
  • All API responses mirror production behavior
  • Balance operations use test balances isolated from production
  • No actual bank transfers or card charges occur

​
Switching Environments

Simply change your API key to switch between test and production: 
# Test mode
curl -H "X-API-Key: qp_test_sk_abc123..." https://api.lux-core.io/api/v1/payments

# Production mode
curl -H "X-API-Key: qp_prod_sk_xyz789..." https://api.lux-core.io/api/v1/payments

​
API Key Scopes

API keys can be configured with specific scopes to limit access:
ScopeDescription
payments.createCreate new payments
payments.readView payment details
payments.viewView payment details (alias for payments.read)
payments.cancelCancel pending payments
payments.methodsAccess payment methods info
webhooks.createCreate webhook endpoints
webhooks.readView webhook configurations
webhooks.viewView webhook configurations (alias for webhooks.read)
webhooks.updateModify webhook settings
webhooks.deleteDelete webhooks
balance.readView account balances
balance.viewView account balances (alias for balance.read)

​
Rate Limits

API requests are rate-limited to ensure fair usage:
Endpoint TypeLimit
Payment creation5000 requests/minute (burst: 500/10sec)
Standard endpoints100 requests/minute
Rate limits are applied per API key. If you exceed the limit, you’ll receive a 429 Too Many Requests response.

​
Error Responses

Authentication errors return standard HTTP status codes:
Status CodeDescription
401 UnauthorizedMissing or invalid API key
403 ForbiddenAPI key lacks required scope
429 Too Many RequestsRate limit exceeded
Example Error Response
{
  "statusCode": 401,
  "message": "Authentication required. Use either Bearer token or X-API-Key header.",
  "error": "Unauthorized"
}

​
Best Practices

Use Environment Variables

Store API keys in environment variables, never in code

Rotate Keys Regularly

Regenerate API keys periodically for security

Use Minimal Scopes

Request only the scopes your application needs

Monitor Usage

Track API usage in the dashboard for anomalies

​
Key Rotation

To rotate your API keys:
  1. Generate a new API key in the Dashboard under Settings -> API Keys
  2. Update your application to use the new key
  3. Verify the new key works correctly
  4. Deactivate the old key in the Dashboard
Multiple API keys can be active simultaneously, allowing zero-downtime rotation. For webhook secret rotation, delete and recreate the webhook endpoint with a new secret.