API Authentication Reference

Authentication Methods

The Trust Leads API supports two authentication methods: API key authentication (recommended for server-to-server integrations) and JWT session tokens (for browser-based access, automatically managed by the dashboard frontend). For all programmatic access, use API key authentication.

API keys are long-lived credentials that do not expire unless you revoke them. JWT session tokens expire after 1 hour and are automatically refreshed by the dashboard. Never use JWT session tokens in server-side code — they are tied to user sessions and will cause authentication failures when the session expires.

Authentication Headers

Pass your API key in the Authorization header as a Bearer token. Alternatively, use the X-API-Key header. Both methods accept the same lfk_ prefixed key. All API requests must be made over HTTPS — HTTP requests will be redirected to HTTPS but it is best practice to always use the HTTPS endpoint directly.

# Bearer token (recommended)
Authorization: Bearer lfk_sk_your_api_key

# X-API-Key header (alternative)
X-API-Key: lfk_sk_your_api_key

# Base URL for all API requests
https://api.trustleads.ai/v1/

Authentication Error Codes

If your request cannot be authenticated, the API returns a 401 Unauthorized response with a JSON body describing the error. Common error codes are MISSING_TOKEN (no Authorization or X-API-Key header provided), INVALID_TOKEN (the key does not match any active key), and REVOKED_TOKEN (the key existed but has been revoked).

A 403 Forbidden response indicates that the key is valid but lacks permission for the requested action. This occurs when a Starter-plan key (read-only API) attempts to submit a new enrichment job. Upgrade your plan to Pro or Agency to gain full API write access.

# 401 Unauthorized — key not found
{
  "error": "INVALID_TOKEN",
  "message": "The provided API key is invalid or does not exist.",
  "docs": "https://trustleads.ai/guides/api-authentication"
}

# 403 Forbidden — insufficient plan
{
  "error": "INSUFFICIENT_PLAN",
  "message": "Job submission via API requires a Pro or Agency plan.",
  "docs": "https://trustleads.ai/guides/billing-plans-comparison"
}