> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/authentication.md).

# Authentication

The helodata REST API authenticates with **Bearer tokens**. Each token belongs to your account and can be scoped to specific resources or actions.

## Get a token

1. **Dashboard → API → New token**.
2. Pick a name and scopes (see below).
3. Copy the token — shown once. We store only a hash; lost tokens cannot be recovered, only rotated.

## Use a token

Send it in the `Authorization` header as `Bearer <token>`:

```bash
curl -H "Authorization: Bearer hel_live_01HXabc..." \
     https://api.helodata.com/v1/users/me
```

## Scopes

| Scope              | Permits                                |
| ------------------ | -------------------------------------- |
| `read`             | Read-only on every resource            |
| `subusers:write`   | Create / update / delete sub-users     |
| `whitelists:write` | Manage IP whitelists                   |
| `orders:write`     | Place and modify orders                |
| `traffic:read`     | Read traffic and usage                 |
| `reports:write`    | Create scheduled reports               |
| `*`                | Full account access (use with caution) |

Scope at the **minimum** needed by each consumer. A common pattern: one read-only token for analytics dashboards, a separate `orders:write` token for the provisioning service.

## Token format

```
hel_live_01HXabc...                # production
hel_test_01HXabc...                # sandbox (coming soon)
```

64 chars after the prefix; cryptographically random.

## Rotation

To rotate a token:

1. **Dashboard → API → {token} → Rotate**.
2. A new token is generated. The old one keeps working for 24 hours, then begins returning `401`.
3. Roll the new token through your deployments before the 24-hour grace expires.

Programmatically:

```bash
curl -X POST -H "Authorization: Bearer EXISTING_KEY" \
     "https://api.helodata.com/v1/tokens/{token_id}/rotate"
```

Returns the new token in the response body.

## Revoke

```bash
curl -X DELETE -H "Authorization: Bearer EXISTING_KEY" \
     "https://api.helodata.com/v1/tokens/{token_id}"
```

Revoked tokens stop working immediately.

## IP allowlist on a token (optional)

Restrict a token to specific source IPs in **Dashboard → API → {token} → Source IPs**. Useful for tokens that only run from a known production environment.

## Error codes

| Status | Code                    | Meaning                                   |
| ------ | ----------------------- | ----------------------------------------- |
| `401`  | `missing_token`         | No `Authorization` header                 |
| `401`  | `invalid_token`         | Token doesn't exist or is malformed       |
| `401`  | `revoked_token`         | Token has been revoked                    |
| `401`  | `expired_token`         | Token's 24-hour rotation grace has ended  |
| `403`  | `insufficient_scope`    | Token lacks the scope this endpoint needs |
| `403`  | `source_ip_not_allowed` | Caller IP isn't on this token's allowlist |

## Security best practices

* **Never commit tokens** to git. Use a secret manager.
* **One token per consumer** — easier to scope, easier to revoke if leaked.
* **Rotate quarterly** at minimum.
* **Monitor** the token's last-used timestamp in **Dashboard → API**; unused tokens should be revoked.