> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heffl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication (Legacy v1)

> How to authenticate with the Heffl legacy API v1

# Authentication

<Note>
  This page covers authentication for the [legacy API v1](/api-reference/introduction). API v2 uses the same `x-api-key` header — see [API v2 Authentication](/api-v2/authentication).
</Note>

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

<Warning>
  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.
</Warning>

## Using your API key

Include the API key in the `x-api-key` header with every request:

```bash theme={null}
curl https://api.heffl.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### JavaScript example

```javascript theme={null}
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

```python theme={null}
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

| Practice                            | Description                                                 |
| ----------------------------------- | ----------------------------------------------------------- |
| **Use environment variables**       | Store API keys in env vars, never hardcode them             |
| **Separate keys per environment**   | Use different keys for development, staging, and production |
| **Rotate periodically**             | Create new keys and revoke old ones on a regular schedule   |
| **Never expose client-side**        | API keys should only be used in server-side code            |
| **Audit usage**                     | Review active keys and revoke any that are unused           |
| **Don't commit to version control** | Add `.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

<AccordionGroup>
  <Accordion title="Can I use Bearer token authentication?">
    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.
  </Accordion>

  <Accordion title="Do API keys expire?">
    API keys do not expire automatically. They remain active until manually revoked.
  </Accordion>

  <Accordion title="Can I restrict an API key to specific endpoints?">
    Currently, API keys have access to all available API endpoints. Endpoint-level restrictions are not yet supported.
  </Accordion>
</AccordionGroup>