# Authentication

> **Network reference:** For the full authentication guide covering all Tools.FAST sites, see [tools.fast/api/docs/authentication](https://tools.fast/api/docs/authentication).

## API key header

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

`X-Fast-Api-Key: fast_prod_...`

Protected public API job endpoints require `X-Fast-Api-Key` from an account with Pro access. Free-tier and other non-Pro API keys return `403 api_key.pro_required` on job submission, job lifecycle, and download routes.

## Server-side only

The API is designed for server-side integrations. Keep API keys on your server and do not ship them in browser bundles or mobile clients.

## Getting your API key

1. [Create an account](/?account=apiKeys&account_source=api-docs).
2. Navigate to **API Keys**.
3. Create a new key -- it will start with `fast_prod_`.
4. Store the key securely; it is shown only once.

Creating an API key does not add credits or Pro API access. Extraction jobs require Pro access and use the credits on your Tools.FAST account.

## Key management

You can create multiple API keys -- for example, separate keys for staging and production, or per application. Revoke any key individually from the **API Keys** page. Revoked keys stop working immediately.

## IP allowlisting

When creating an API key, you can restrict it to specific IP addresses. Enter a single address, such as `203.0.113.5`, or a CIDR range, such as `203.0.113.0/24`. Requests from non-allowlisted IPs are rejected with `401`.

We recommend allowlisting your server IPs in production; it limits the blast radius if a key is ever leaked.

## Entitlements

Use `GET /entitlements/me` before large workflows to show available credits or decide whether to ask the user to add credits.

```bash
curl https://api.tools.fast/extract/entitlements/me \
  -H "X-Fast-Api-Key: $API_KEY"
```

Typical response:

```json
{
  "userId": "018f2f39-8b29-7a9f-a4be-02c59a21716d",
  "organizationId": "018f2f39-8b29-7a9f-a4be-02c59a21716e",
  "planId": "pro",
  "planName": "Pro",
  "accessDisplayName": "Pro",
  "totalCredits": 29366,
  "planCredits": 29000,
  "loyaltyCredits": 100,
  "walletCredits": 266,
  "source": "accounts.fast",
  "tier": "pro"
}
```

`totalCredits` is the sum available to the account. The three credit-bucket fields
show its current composition. Free and guest responses use the same flat credit
fields and also include their daily limit, usage, and reset date.

## Missing or invalid keys

Missing, expired, or invalid API keys return a stable `401` error response. Do not
parse prose fields; branch on the `error` or identical `code` value and HTTP status.

A missing key returns:

```json
{
  "error": "api_key.required",
  "code": "api_key.required"
}
```

An expired, malformed, invalid, or non-allowlisted key returns:

```json
{
  "error": "api_key.invalid_or_ip_not_allowed",
  "code": "api_key.invalid_or_ip_not_allowed"
}
```

Free-tier and other non-Pro API keys return:

```json
{
  "error": "api_key.pro_required",
  "code": "api_key.pro_required",
  "params": {
    "requiredTier": "pro",
    "currentTier": "free"
  }
}
```