Authentication

Every endpoint in the Holofin API requires an API key. This page covers how to send it, how to restrict a key by IP or expiry, and the errors returned when authentication fails.

API Key Authentication

Send your API key in the X-API-Key header on every request. Requests must use HTTPS; calls over plain HTTP fail, and so do calls without a key. The examples in these docs read the key from $HOLOFIN_API_KEY: export HOLOFIN_API_KEY=sk-holo-...

curl "https://app.holofin.ai/api/v1.1/workflow-runs/?limit=1" \
  -H "X-API-Key: $HOLOFIN_API_KEY"

Never commit an API key to a repository.

Creating API Keys

Create API keys in your workspace settings. You can create a separate key for each integration or environment.

IP Allowlisting

You can restrict an API key to specific IP addresses or CIDR ranges. Once set, only requests from the allowed IPs are accepted.

• Navigate to Settings → API Keys
• Click the options menu (…) on a key
• Select "IP Whitelist"
• Add one IP address or CIDR range per line
  Supports IPv4, IPv6, and CIDR notation (e.g., 192.168.1.0/24). Leave empty to allow requests from any IP.

When a request is rejected due to IP restrictions, the API returns:

{
  "error": "Request from this IP address is not allowed."
}

Key Expiration

API keys can be created with an expiration date. When creating a key, choose from preset durations (1 month, 3 months, 6 months, 1 year) or set a custom date. Keys without an expiration date remain valid until manually disabled or deleted.

When an expired key is used, the API returns:

{
  "error": "API key has expired."
}

Authentication Error Responses

When authentication fails, the API will return one of the following error responses:

401 - Missing API Key

This error occurs when no X-API-Key header is provided.

{
  "error": "API key required in X-API-Key header."
}

403 - Invalid or Inactive API Key

This error occurs when the provided API key is invalid, inactive, or has been revoked.

{
  "error": "Invalid or inactive API key."
}