Authentication

The Lead Hero API uses organization API keys for authentication. Every request must include a valid API key.

Obtaining an API Key

1. Log in to app.leadhero.io
2. Go to Settings → API Keys
3. Click Create API Key, give it an optional label and expiration date, then copy the key — it is shown only once and cannot be retrieved again

Key Format

API keys have two parts separated by a .:

<uuid>.<base64url-secret>

Example:

a3f8c2d1-4e5b-6f7a-8b9c-0d1e2f3a4b5c.X9kLmNpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789AB

• The first part is a UUID that identifies which key record to look up.
• The second part is a 32-byte random secret encoded as base64url (~43 characters).
• Only the hashed secret is stored server-side; the plaintext is never persisted.

Sending the API Key

You can authenticate in two ways:

Option 1 — Bearer Token (recommended)

Include the key in the Authorization header:

Authorization: Bearer a3f8c2d1-4e5b-6f7a-8b9c-0d1e2f3a4b5c.X9kLmNpQrStUv...

Option 2 — x-api-key Header

x-api-key: a3f8c2d1-4e5b-6f7a-8b9c-0d1e2f3a4b5c.X9kLmNpQrStUv...

Example Request

curl https://api.leadhero.io/leads \
  -H "Authorization: Bearer a3f8c2d1-4e5b-6f7a-8b9c-0d1e2f3a4b5c.X9kLmNpQrStUv..."

Expiration & Revocation

• Keys expire 6 months from creation by default; you can set a custom expiration date at creation time.
• Revoke a key at any time from Settings → API Keys. Revocation is immediate and permanent.
• Expired or revoked keys return 401 Unauthorized.

Security Notes

• Copy your key immediately after creation — it is never shown again.
• Keep your API key secret; treat it like a password.
• Rotate keys immediately if compromised via Settings → API Keys.
• Each key is scoped to your organization; it authenticates as the highest-privilege active member.