Authentication

All checkout API endpoints (except the public payment page) require authentication. The API supports three authentication methods, checked in this order:

1. API Key (recommended for integrations)

Pass your API key in the X-Api-Key header:

curl -H "X-Api-Key: fc_live_abc123..." \
  https://fincobra.com/api/checkout/invoices

API keys are prefixed with fc_live_ and are hashed (SHA-256) before storage — the raw key is only shown once at creation time.

2. Session cookie

Browser-based requests from the FinCobra dashboard use a session cookie containing a signed JWT. This is handled automatically when you're logged in.

3. Bearer token

Pass a JWT in the Authorization header:

curl -H "Authorization: Bearer eyJhbGci..." \
  https://fincobra.com/api/checkout/invoices

Managing API keys

API keys are managed through the main FinCobra API (not the checkout API). You can have up to 3 active keys at a time.

Method	Path	Description
POST	/api/users/:id/checkout-api-key	Generate a new API key
GET	/api/users/:id/checkout-api-keys	List active keys (prefix only)
DELETE	/api/users/:id/checkout-api-key/:keyId	Revoke a key

Generate a key

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}' \
  https://fincobra.com/api/users/:id/checkout-api-key

Response:

{
  "id": "42",
  "rawKey": "fc_live_a1b2c3d4...",
  "keyPrefix": "fc_live_a1b2",
  "label": "production",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

WARNING

Copy the rawKey immediately — it is not stored and cannot be retrieved later.

List keys

Returns only the key prefix (first 12 characters) for identification:

{
  "keys": [
    {
      "id": "42",
      "keyPrefix": "fc_live_a1b2",
      "label": "production",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Revoke a key

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://fincobra.com/api/users/:id/checkout-api-key/42

Revoked keys stop working immediately. This cannot be undone.

Error responses

All authentication errors return HTTP 401:

{
  "error": "Invalid API key"
}