Authentication

Merchant integrations authenticate with an API key in the X-Api-Key header.

curl -X POST https://fincobra.com/api/checkout/invoices \
  -H "X-Api-Key: fc_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": 49.99,
    "merchantReference": "order_123"
  }'

Generate an API key

Create and manage API keys from the FinCobra dashboard.

1. Open the Checkout dashboard.
2. Go to Checkout settings.
3. Generate an API key.
4. Copy the raw key immediately.
5. Store it in your server-side environment or secret manager.

API keys are prefixed with fc_live_. The raw key is shown once at creation time and cannot be retrieved later. FinCobra stores only a SHA-256 hash of the key.

WARNING

Do not put API keys in browser code, mobile apps, public repositories, or client-side environment variables. Use them only from your server.

Available API

API keys are integration credentials. They can create invoices and read known invoice data:

Method	Path	Description
POST	/api/checkout/invoices	Create an invoice
GET	/api/checkout/invoices/:id	Get invoice detail
GET	/api/checkout/invoices/:id/status	Get invoice status

API keys cannot list all invoices or change Checkout configuration. Store the invoice id returned by POST /api/checkout/invoices with your order, then use that known id for later lookups. Checkout configuration, payment methods, webhook settings, exports, exception review, and key rotation are handled in the FinCobra dashboard.

Rate Limits

API-key-authenticated checkout requests are limited to 100 requests per minute from the same client. This applies to invoice create, invoice detail, and invoice status calls made with the X-Api-Key header.

If you exceed the limit, the API returns HTTP 429 with a human-readable error message. Retry after the time shown in the error response.

Errors

Requests without an API key or dashboard session return HTTP 401:

{
  "error": "Missing API key or session"
}

Invalid API keys also return HTTP 401:

{
  "error": "Invalid API key"
}

API keys require an enabled account. A disabled account receives HTTP 403 with { "error": "Forbidden" }. This also applies to WooCommerce installation keys. Enabling the account restores access through keys that have not been revoked.

If account status cannot be verified, authenticated requests return HTTP 503. Retry after the service recovers.

Account security

Private Checkout list routes use the authenticated account. Do not add a userId or user_id query field to select another account. A confirmed cross-account probe can disable the calling account and revoke its sessions and MCP access tokens. Admin account management uses the Console routes.