Skip to main content

​
Authentication

The Heffl API uses API keys for authentication. Every request must include a valid API key.

​
Getting your API key

  1. Go to Settings > Developer in your Heffl dashboard
  2. Click Create API Key
  3. Name your key to identify its purpose (e.g., “Website Forms”, “Data Sync”)
  4. Copy the API key immediately
Your API key is shown only once when created. Copy it and store it securely. If you lose it, you’ll need to create a new one.

​
Using your API key

Include the API key in the x-api-key header with every request: 
curl https://api.heffl.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
JavaScript example

const response = await fetch("https://api.heffl.com/api/v1/leads", {
  headers: {
    "x-api-key": process.env.HEFFL_API_KEY,
    "Content-Type": "application/json",
  },
});

const data = await response.json();

​
Python example

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.heffl.com/api/v1/leads",
    headers=headers
)

data = response.json()

​
API key scope

API keys operate at the workspace level. A key has access to all data within the workspace it was created in, subject to the same data boundaries as the user who created it.

​
Revoking API keys

To revoke an API key:
  1. Go to Settings > Developer
  2. Find the key in the list
  3. Click Revoke
Revoked keys stop working immediately. Any integration using that key will receive 401 Unauthorized responses.

​
Security best practices

PracticeDescription
Use environment variablesStore API keys in env vars, never hardcode them
Separate keys per environmentUse different keys for development, staging, and production
Rotate periodicallyCreate new keys and revoke old ones on a regular schedule
Never expose client-sideAPI keys should only be used in server-side code
Audit usageReview active keys and revoke any that are unused
Don’t commit to version controlAdd .env files to .gitignore

​
Troubleshooting

​
401 Unauthorized

  • Verify the API key is included in the x-api-key header (not Authorization)
  • Check that the key hasn’t been revoked
  • Ensure there are no extra spaces or line breaks in the key

​
403 Forbidden

  • The API key is valid but doesn’t have access to the requested resource
  • Check that the key was created in the correct workspace

​
FAQ

No. The Heffl API exclusively uses the x-api-key header for authentication. Bearer tokens are used internally for the web app but are not available for API access.
API keys do not expire automatically. They remain active until manually revoked.
Currently, API keys have access to all available API endpoints. Endpoint-level restrictions are not yet supported.