Authentication

The LeadHQL API uses API keys for authentication. Keys are scoped to your organization and provide access to all properties and agents within it.

API Key Format

All API keys use the prefix leadhql_pk_ followed by a random string:

Creating API Keys

You can create API keys from the LeadHQL dashboard under Integrations, or programmatically via the API using a JWT session token.

Via the API

curl -X POST https://api.leadhql.com/api-keys \
  -H "Authorization: Bearer <jwt-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "expiresInDays": 90
  }'

Request body:

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | A label to identify this key | | expiresInDays | number | No | Days until the key expires. Omit for a non-expiring key. |

Response:

{
  "id": "a1b2c3d4-...",
  "name": "My Integration",
  "key": "leadhql_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "status": "active",
  "createdAt": "2026-03-01T12:00:00.000Z",
  "expiresAt": "2026-05-30T12:00:00.000Z"
}

The full key is only returned once at creation time. Store it securely — you cannot retrieve it later.

Using API Keys

Include the key in the Authorization header as a Bearer token:

curl https://api.leadhql.com/properties/stats/counts \
  -H "Authorization: Bearer leadhql_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Listing API Keys

Retrieve all keys for your organization. The key value itself is not included — only metadata.

curl https://api.leadhql.com/api-keys \
  -H "Authorization: Bearer <jwt-session-token>"

Response:

[
  {
    "id": "a1b2c3d4-...",
    "name": "My Integration",
    "status": "active",
    "createdAt": "2026-03-01T12:00:00.000Z",
    "lastUsedAt": "2026-03-05T09:15:00.000Z",
    "usageCount": 247,
    "expiresAt": "2026-05-30T12:00:00.000Z"
  }
]

Each key tracks usageCount (total requests made) and lastUsedAt (timestamp of most recent use).

Revoking API Keys

Permanently deactivate a key by its ID:

curl -X DELETE https://api.leadhql.com/api-keys/a1b2c3d4-... \
  -H "Authorization: Bearer <jwt-session-token>"

{
  "success": true
}

Revoked keys immediately stop working. This action cannot be undone — create a new key if needed.

Key Lifecycle

1. Create — Generate a key with an optional expiration date
2. Use — Include it in the Authorization header for API requests
3. Monitor — Check usageCount and lastUsedAt via the list endpoint
4. Revoke — Delete the key when it is no longer needed

Security Best Practices

• Store keys in environment variables or a secrets manager — never commit them to source control
• Use expiring keys for integrations that are time-limited
• Rotate keys periodically by creating a new key, updating your integration, then revoking the old one
• Monitor usage counts to detect unexpected activity

API Key vs. JWT Authentication

API key management endpoints (POST /api-keys, GET /api-keys, DELETE /api-keys/:id) require a JWT session token from the dashboard — you cannot create or revoke keys using another API key.

All other endpoints (properties, agents, search) accept either authentication method.