Authentication

​

What an API key is

• It belongs to one organization. The dashboard calls an organization a workspace. The key belongs to the workspace you are in when you create it. Every request made with it acts as that organization and counts toward its API allowance.
• It starts with dnst_. The dashboard lists only the first 12 characters, followed by ….
• It is shown once. The dashboard shows the full key right after you create it. DarknetSearch stores a hash of the key and its first 12 characters, so nobody can show you the full key again.
• It works on its own. Each key is separate. Revoking one key leaves your other keys working.
• It can expire. You choose when you create it: never, 30 days, 90 days or 1 year.

​

Create a key

​

Send the key

curl https://client-api.leak.center/api/service/get_direct_org_info/ \
  -H "X-API-Key: YOUR_API_KEY"

import os
import requests

response = requests.get(
    "https://client-api.leak.center/api/service/get_direct_org_info/",
    headers={"X-API-Key": os.environ["DARKNETSEARCH_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json()["name"])

async function main() {
  const response = await fetch(
    "https://client-api.leak.center/api/service/get_direct_org_info/",
    { headers: { "X-API-Key": process.env.DARKNETSEARCH_API_KEY } },
  );
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  console.log((await response.json()).name);
}

main();

{
  "id": 412,
  "name": "Acme Corp",
  "domain": "acme.com",
  "is_direct_org": true,
  "main_org_id": null
}

​

Keep the key secret

• Call the API from a server. Use your backend, a script or your SIEM. The API does not accept the X-API-Key header from browser pages on other websites, so a web front end cannot send it directly.
• Store the key in a secret manager or an environment variable. Keep it out of source code, logs and version control.
• Create one key per integration. Name each key after the integration that uses it. You can then revoke one key without breaking the others.

​

Expiry, revocation and rotation

HTTP/1.1 401 Unauthorized

{ "detail": "Invalid or expired API key." }

• Expired keys stay in the list, marked Expired, until you revoke them. You cannot extend a key. Create a new one.
• Revoked keys leave the list. To revoke a key, open Manage → API tokens, click Revoke on its row, and confirm with Revoke token. Anything still using the key stops working at once. You cannot undo a revocation.

​

Errors

HTTP/1.1 429 Too Many Requests
Retry-After: 2037599

{
  "message": "Rate limit exceeded",
  "retry_after_seconds": 2037599,
  "limit": 5000,
  "remaining": 0,
  "reset_at": "2026-10-31T23:59:59.250000+00:00"
}

​

Usage and limits

• Only 2xx responses use up the allowance. A call that ends in any other status is refunded. A call rejected with 401, 403 or 429 is never counted against the allowance. get_api_call_usage still lists 403 and 429 responses in its per-status counts.
• Every 2xx and 429 response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. X-RateLimit-Reset is the number of seconds until that limit resets. The headers describe whichever limit has the fewest requests left. On a 429 they describe the limit you hit.

​

Client organizations

• From your own organization. Most partners do this. Register each client’s domains and other assets in your own organization with organization_assets_create or under Manage → Assets, then monitor and scan them with your own key. Only your team signs in, and every client uses your plan, allowances and slots. Use label on each asset to note which client it belongs to.
• From a client workspace. A client workspace is a separate organization, bought for a client that signs in to the dashboard itself, with its own users and plan. The API calls it a client organization: its profile’s main_org_id is your organization’s id. It needs its own key. As a System Admin, pick the client workspace in the workspace switcher, open Manage → API tokens and create the key there. It belongs to that client workspace.

​

Where to manage keys

​

Endpoints