Skip to main content
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"

​
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

ClaimDescription
iatIssued At — Unix timestamp of when the token was created
expExpiration Time — Unix timestamp when the token expires. Must be within one week of iat.
nameYour 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}"}

​
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:
ZoneSearch APIManagement & Stats APIRecommendations APICategory Merchandising
eu1eu1-search.doofinder.comeu1-api.doofinder.comeu1-recommendations.doofinder.comeu1-category-merchandising.doofinder.com
us1us1-search.doofinder.comus1-api.doofinder.comus1-recommendations.doofinder.comus1-category-merchandising.doofinder.com
ap1ap1-search.doofinder.comap1-api.doofinder.comap1-recommendations.doofinder.comap1-category-merchandising.doofinder.com
Your zone is visible in the Doofinder Admin Panel and is also encoded in your API key prefix.