Authentication - Doofinder API Reference

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 under Account → API Keys. One key covers all APIs — Search, Management, and Stats.

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

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:

curl "https://eu1-search.doofinder.com/6/{hashid}/_search?query=shoes" \
  -H "Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07"

curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
  -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"

curl "https://eu1-api.doofinder.com/api/v2/stats/searches" \
  -H "Authorization: Token ab46030xza33960aac71a10248489b6c26172f07"

JWT Authentication

The Management API and Stats API also support JSON Web Tokens (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:

curl "https://eu1-api.doofinder.com/api/v2/search_engines" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE2ODQ1ODIyfQ.xxxxx"

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}"}

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}` };

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:

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"}'

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.

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`

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

​API Keys

​Key format

​Token Authentication

​JWT Authentication

​Required JWT claims

​Signing

​Usage

​Recommendations API

​Service zones

API Keys

Key format

Token Authentication

JWT Authentication

Required JWT claims

Signing

Usage

Recommendations API

Service zones