Authentication

The Cludo API supports two authentication schemes. Which one to use depends on where the request is made and which endpoint you call.

Scheme	Use case
Basic (API Key)	Default for API requests, server-side integrations, index management, crawler URL queues, and search tools
SiteKey	Public client-side search where an API key must not be exposed

Unless an endpoint says otherwise, use Basic authentication. SiteKey is only intended for browser-facing search integrations.

Basic (API Key) authentication

Used for API requests from a trusted backend, scripts, and integrations. Use Basic authentication for index management, crawler URL queues, search tools, and any endpoint where you can keep the API key private.

Building the token

# Format: base64(customerId:apiKey)
echo -n "3:c8fk2L9mK4pQ" | base64
# MzpjOGZrMkw5bUs0cFE=

# Use https://api-us1.cludo.com for the US region
curl -X POST "https://api.cludo.com/api/v4/3/6/search" \
  -H "Authorization: Basic MzpjOGZrMkw5bUs0cFE=" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

import requests

# Use https://api-us1.cludo.com for the US region
url = "https://api.cludo.com/api/v4/3/6/search"
headers = {
    "Authorization": "Basic MzpjOGZrMkw5bUs0cFE=",
    "Content-Type": "application/json",
}

response = requests.post(url, json={"query": "test"}, headers=headers)
print(response.json())

// Use https://api-us1.cludo.com for the US region
const response = await fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": "Basic MzpjOGZrMkw5bUs0cFE=",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "test" }),
});

const data = await response.json();
console.log(data);

// Use https://api-us1.cludo.com for the US region
const response = await fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": "Basic MzpjOGZrMkw5bUs0cFE=",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "test" }),
});

const data: unknown = await response.json();
console.log(data);

Where to find your credentials

SiteKey authentication

Used for public website search widgets and other client-side search integrations. SiteKey authentication exists so browser code can call search-related endpoints without exposing your API key.

Building the token

# Format: base64(customerId:engineId:SearchKey)
# "SearchKey" is a fixed, literal string. Do not replace it with a value.
echo -n "3:6:SearchKey" | base64
# Mzo2OlNlYXJjaEtleQ==

A SiteKey is tied to one specific engine. You cannot use a SiteKey from one engine to authenticate requests to another engine.

# Use https://api-us1.cludo.com for the US region
curl -X POST "https://api.cludo.com/api/v4/3/6/search" \
  -H "Authorization: SiteKey Mzo2OlNlYXJjaEtleQ==" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'

import requests

# Use https://api-us1.cludo.com for the US region
url = "https://api.cludo.com/api/v4/3/6/search"
headers = {
    "Authorization": "SiteKey Mzo2OlNlYXJjaEtleQ==",
    "Content-Type": "application/json",
}

response = requests.post(url, json={"query": "test"}, headers=headers)
print(response.json())

// Use https://api-us1.cludo.com for the US region
const response = await fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": "SiteKey Mzo2OlNlYXJjaEtleQ==",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "test" }),
});

const data = await response.json();
console.log(data);

// Use https://api-us1.cludo.com for the US region
const response = await fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": "SiteKey Mzo2OlNlYXJjaEtleQ==",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "test" }),
});

const data: unknown = await response.json();
console.log(data);

Try it: build your token

Use the tool below to generate your SiteKey or Basic authorization header and a ready-to-run cURL command. Switch between SiteKey and Basic to see the correct prefix for each scheme.

Get Started

Guides

Concepts

Help

Basic (API Key) authentication

Building the token

Where to find your credentials

SiteKey authentication

Building the token

Try it: build your token

​Basic (API Key) authentication

​Building the token

​Where to find your credentials

​SiteKey authentication

​Building the token

​Try it: build your token

Basic (API Key) authentication

Building the token

Where to find your credentials

SiteKey authentication

Building the token

Try it: build your token