Authentication

Every request to api.lidya.money must carry an X-API-Key header.

curl https://api.lidya.money/v1/balance \
  -H "X-API-Key: sk_test_8k3F_mEh7..."

Key formats

Test keys never settle to your wallet — they're for integration work. Live keys are billable.

Scopes

Each key carries an array of scopes. The current set:

• read — list and fetch resources
• write — create charges, refunds, and other state changes
• payouts — initiate crypto payouts (separately gated, off by default)
• all — everything (issue these sparingly)

A request with a scope the key lacks returns 403 forbidden with code insufficient_scope.

IP allowlists

Keys can be locked to a CIDR list. We recommend this for production keys:

curl -X POST https://api.lidya.money/v1/api-keys \
  -H "X-API-Key: sk_live_owner_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["read","write"],
    "allowedIps": ["203.0.113.7/32", "198.51.100.0/24"]
  }'

A request from outside the allowlist returns 401 unauthorized with code ip_not_allowed.

Rotation

Keys are immutable — we never re-issue an old prefix. To rotate:

1. Issue a new key with the same scopes.
2. Roll the new key into your deployment.
3. Verify traffic is using the new key (check lastUsedAt on both).
4. Revoke the old key.

Lidya keeps a 30-day grace period on revoked keys — they immediately fail auth, but the audit log retains the linkage so you can trace anything that ran while the key was live.

Webhook signing

Webhooks are signed separately with a per-endpoint secret. See Webhooks for the verification flow.

What never leaves your server

Never put your API key in a frontend bundle or mobile binary. Lidya's hosted checkout means card data never touches your servers — and it should never touch your client either. If you find yourself wanting to send cardNumber to our API, stop and read Charges.