API Authentication

All API requests require authentication using an API key.

API keys

API keys start with the hklst_ prefix and are scoped to an organization. They provide the same access as a logged-in user within that organization.

Creating an API key

1. Go to Organization Settings > API Keys in the dashboard
2. Click Create API Key
3. Enter a name for the key
4. Copy the key — it's only shown once

Or via the API (requires an existing key):

curl -X POST https://app.hooklistener.com/api/v1/organizations/<org-id>/api-keys \
  -H "Authorization: Bearer hklst_your_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Using an API key

Include the key in the Authorization header:

curl https://app.hooklistener.com/api/v1/endpoints \
  -H "Authorization: Bearer hklst_your_api_key"

Organization context

API keys are automatically scoped to their organization. All requests return data for the organization the key belongs to.

If you're using JWT authentication (e.g., from the device code flow), you need to specify the organization:

curl https://app.hooklistener.com/api/v1/endpoints \
  -H "Authorization: Bearer <jwt_token>" \
  -H "x-organization-id: <organization-id>"

Authentication errors

Status	Meaning
401 Unauthorized	Missing or invalid API key
403 Forbidden	Key doesn't have access to the requested resource

{
  "error": "Authentication required"
}

Security best practices

• Never commit API keys to source control
• Use environment variables to store keys
• Create separate keys for different environments (development, CI, production)
• Revoke keys that are no longer needed
• Rotate keys periodically