Authentication and API keys

Every request to https://platform.detectif.ai/v1, except GET /v1/health, needs an API key in the Authorization header:

Authorization: Bearer dtf_live_...

#Key format

API keys start with dtf_live_ followed by 43 letters and digits. The server stores only a keyed hash of each key, so the full key is shown once, when you create it. If you lose a key, rotate or revoke it and create a new one.

#Send the key in a header, never in a URL

Keys are accepted only in the Authorization header. A request with an api_key query parameter is rejected with 400 api_key_in_url, because URLs are written to logs, browser history and proxies. If a key was sent in a URL, rotate it.

curl https://platform.detectif.ai/v1/credits \
  -H "Authorization: Bearer $DETECTIF_API_KEY"

import os
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DETECTIF_API_KEY']}"

resp = session.get("https://platform.detectif.ai/v1/credits", timeout=30)
print(resp.status_code, resp.json())

const headers = { Authorization: `Bearer ${process.env.DETECTIF_API_KEY}` };

const res = await fetch("https://platform.detectif.ai/v1/credits", { headers });
console.log(res.status, await res.json());

#Scopes

Each key carries a list of scopes chosen when it is created. A request that needs a scope the key does not have fails with 403 insufficient_scope, and nothing is charged.

GET /v1/operations/{operation_id} accepts any scope that covers the original operation. For example, a key with deepfake:detect can read the stored result of a deepfake detection.

A verification with detect_deepfake=true needs both speakers:verify and deepfake:detect.

Give each key only the scopes it needs. A service that only verifies callers needs speakers:verify; an enrollment back office needs speakers:enroll, speakers:read and speakers:delete.

#Managing keys

Keys are managed in the dashboard under API keys:

• Create: name the key (1 to 64 characters), choose scopes, copy the key once. An account can have up to 20 active keys.
• Rotate: issues a new key with the same name and scopes and revokes the old key at once. Have the new key ready to deploy before you rotate. To change keys without a gap, create a second key, deploy it, then revoke the first.
• Revoke: the key stops working on the next request. Requests with a revoked key fail with 401 revoked_api_key.

Keys are checked on every request without caching, so rotation and revocation take effect immediately. The dashboard shows each key's prefix, scopes, creation time and last use, never the full key.

Creating, rotating and revoking keys is free and never grants credits.

#Dashboard sessions

The dashboard calls the same /v1 endpoints with your signed-in session token instead of an API key. Sessions have all scopes. Use API keys, not session tokens, in your own code.

#Keep keys secret

• Call the API from your servers. Do not put keys in browser code, mobile apps or other software you distribute.
• Use one key per service and environment, so you can revoke one without affecting the others.
• Load keys from environment variables or a secret manager. Do not commit them.
• If a key may have been exposed, rotate or revoke it in the dashboard.

#Authentication errors

Authentication failures are never charged. See Errors for the full error envelope.