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>:

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:

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

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.