Skip to main content
Every request you make to the Clodura API must be authenticated with a personal API key. Clodura uses a simple API-key scheme — there are no OAuth flows, no session tokens, and no cookies to manage. You include your key in a single HTTP request header, and the API validates it on every call. This page walks you through obtaining your key, adding it to requests, securing it properly, and understanding what happens when authentication fails.

​
How Authentication Works

Clodura authenticates API requests using the X-API-KEY header. You send your API key with every HTTP request, and the API checks it before processing anything else. Requests with a missing or invalid key are rejected immediately with a 401 Unauthorized response. 
X-API-KEY: your_api_key_here
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Your API key is a secret credential — treat it like a password.

​
Getting Your API Key

You can find and manage your API key inside the Clodura application.
1

Log in to Clodura

Go to app.clodura.ai and sign in with your account credentials.
2

Open Settings

Click your name or initials in the upper-right corner of the dashboard to open the account menu, then select Settings.
3

Navigate to the Developer Dashboard

Inside Settings, find the Developer or API section. Your API key is displayed here. If no key exists yet, use the Generate Key button to create one.
4

Copy your key securely

Copy the key and store it in a secure location such as a password manager or a secrets vault. You will not be able to view the full key again after leaving the page — if you lose it, you will need to regenerate a new one.
Never share your API key. Do not commit it to source control (GitHub, GitLab, etc.), embed it in client-side JavaScript, or include it in publicly accessible configuration files. Your key carries the same privileges as your account — anyone who obtains it can consume your credits.

​
Adding Your Key to Requests

Set the X-API-KEY header on every API call. The examples below show how to do this in both curl and Python.

​
curl

curl -X POST https://api.clodura.ai/api/v1/search/people \
  -H 'X-API-KEY: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Smith"}'

​
Python (requests)

import requests

headers = {
    'X-API-KEY': 'your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.clodura.ai/api/v1/search/people',
    headers=headers,
    json={'name': 'John Smith'}
)

print(response.status_code)
print(response.json())
Store your API key in an environment variable and read it at runtime rather than hard-coding it in your source files. For example:
export CLODURA_API_KEY="your_api_key_here"

import os, requests

headers = {
    'X-API-KEY': os.environ['CLODURA_API_KEY'],
    'Content-Type': 'application/json'
}
This keeps secrets out of your codebase and makes it easy to rotate keys without a code change.

​
Security Best Practices

Following these practices protects your account and prevents unexpected credit consumption.

Use Environment Variables

Load your key from an environment variable or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) at runtime. Never hard-code it in source files.

Keep It Out of Source Control

Add .env files and any config file containing your key to your .gitignore. Scan your commit history with tools like git-secrets before making a repository public.

Restrict Server-Side Use

Only call the Clodura API from your backend server or serverless functions — never from browser-side JavaScript, mobile apps, or any environment where the key could be inspected by an end user.

Rotate Keys Regularly

Regenerate your API key periodically or immediately if you suspect it has been exposed. Update all services that use the old key before invalidating it.

​
Authentication Error Responses

When a request fails for an authentication or authorisation reason, the API returns a JSON body with a message field describing the problem.

​
401 Unauthorized

Returned when the X-API-KEY header is missing entirely, contains a malformed value, or the key does not exist in Clodura’s system. 
{
  "message": "Unauthorized"
}
Fix: Check that you are sending the X-API-KEY header and that the key value matches exactly what is shown in your Developer Dashboard — including case sensitivity.

​
403 Forbidden

Returned when your API key is valid but your subscription plan does not permit the requested operation. For example, accessing an endpoint that requires an Enterprise plan when you are on a Starter plan. 
{
  "message": "Forbidden"
}
Fix: Review your plan’s capabilities in the Clodura dashboard, or upgrade your plan to unlock the endpoint you need.

​
429 Too Many Requests

Returned when your account exceeds the per-second or per-minute rate limit for your plan. See the rate limit table below. 
{
  "message": "Rate limit exceeded"
}
Fix: Slow down your request cadence and implement exponential backoff. Wait for the rate limit window to reset before retrying.

​
Rate Limits by Plan

Rate limits are enforced per API key. Exceeding your daily limit returns 409 Conflict instead of 429.
PlanPer SecondPer MinutePer Day
MAX101002,000
PayG101002,000
Professional101002,000
Enterprise101002,000
Prospect Pro101002,000
Prospect101002,000
Starter110600
Lifetime110300
Basic110600
Default / Free Forever110300
Your current plan and remaining daily quota are visible in the Clodura dashboard under Settings → Usage Report. You can also query remaining credits programmatically via GET https://api.clodura.ai/api/v1/credits.