> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doofinder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with Doofinder APIs.

All Doofinder APIs require authentication via the `Authorization` HTTP header. The exact format and key type vary by API.

## API Keys

Generate an API key in the [Doofinder Admin Panel](https://admin.doofinder.com/admin/account/api) under **Account → API Keys**. One key covers all APIs — Search, Management, and Stats.

<Warning>
  Only the API key of the **account owner** is valid for API operations. Keys generated by team members will not work.
</Warning>

### Key format

The same key works across all APIs. You may see it written with a zone prefix (e.g. `eu1-ab46030x...`) — this prefix is optional and ignored by the API. Both formats are valid:

```
eu1-ab46030xza33960aac71a10248489b6c26172f07   ← zone prefix included (optional)
ab46030xza33960aac71a10248489b6c26172f07        ← no prefix (also valid)
```

The zone that serves your request is determined by the **hostname** you call, not by the key.

***

## Token Authentication

Pass the API key in the `Authorization` header as a `Token`:

<CodeGroup>
  ```bash Search API theme={null}
  curl "https://eu1-search.doofinder.com/6/{hashid}/_search?query=shoes" \
    -H "Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07"
  ```

  ```bash Management API theme={null}
  curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
    -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"
  ```

  ```bash Stats API theme={null}
  curl "https://eu1-api.doofinder.com/api/v2/stats/searches" \
    -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"
  ```
</CodeGroup>

***

## JWT Authentication

The Management API and Stats API also support [JSON Web Tokens](https://jwt.io) (JWT) as an alternative to static API keys. JWTs are useful when you need short-lived credentials or want to avoid embedding long-lived secrets in client code.

### Required JWT claims

| Claim  | Description                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------- |
| `iat`  | Issued At — Unix timestamp of when the token was created                                       |
| `exp`  | Expiration Time — Unix timestamp when the token expires. Must be within **one week** of `iat`. |
| `name` | Your Doofinder user code — find it in your Admin Panel profile                                 |

### Signing

Sign the JWT with your **API management key** using the `HS256` algorithm.

### Usage

Send the JWT in the `Authorization` header as a `Bearer` token:

```bash theme={null}
curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE2ODQ1ODIyfQ.xxxxx"
```

<CodeGroup>
  ```python Python (PyJWT) theme={null}
  import jwt
  import time

  payload = {
      "name": "your-user-code",
      "iat": int(time.time()),
      "exp": int(time.time()) + 3600  # 1 hour
  }

  token = jwt.encode(payload, "your-api-management-key", algorithm="HS256")
  headers = {"Authorization": f"Bearer {token}"}
  ```

  ```javascript JavaScript (jsonwebtoken) theme={null}
  const jwt = require("jsonwebtoken");

  const token = jwt.sign(
    { name: "your-user-code" },
    "your-api-management-key",
    { algorithm: "HS256", expiresIn: "1h" }
  );

  const headers = { Authorization: `Bearer ${token}` };
  ```
</CodeGroup>

***

## Recommendations API

The Recommendations API does not use the `Authorization` header. The **widget ID** (a UUID) serves as the credential and is passed directly in the URL path:

```bash theme={null}
curl -X POST "https://eu1-recommendations.doofinder.com/api/widget/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{"current_url": "https://shop.example.com/products/shoes"}'
```

<Note>
  CORS is enforced on the Recommendations API. The `Origin` and `Referer` headers must match a domain configured in your store settings, or requests will be rejected with `403 Forbidden Origin`.
</Note>

***

## Service zones

Your Doofinder account is assigned to a specific zone. All API calls must go to the correct zone hostname:

| Zone  | Search API                 | Management & Stats API  | Recommendations API                 | Category Merchandising                     |
| ----- | -------------------------- | ----------------------- | ----------------------------------- | ------------------------------------------ |
| `eu1` | `eu1-search.doofinder.com` | `eu1-api.doofinder.com` | `eu1-recommendations.doofinder.com` | `eu1-category-merchandising.doofinder.com` |
| `us1` | `us1-search.doofinder.com` | `us1-api.doofinder.com` | `us1-recommendations.doofinder.com` | `us1-category-merchandising.doofinder.com` |
| `ap1` | `ap1-search.doofinder.com` | `ap1-api.doofinder.com` | `ap1-recommendations.doofinder.com` | `ap1-category-merchandising.doofinder.com` |

<Tip>
  Your zone is visible in the Doofinder Admin Panel and is also encoded in your API key prefix.
</Tip>