Source: https://fincobra.com/docs/checkout/authentication.html


# Authentication

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

```bash
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`:

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

Invalid API keys also return HTTP `401`:

```json
{
  "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.