Authentication

All OneHazel API calls require authentication. This page covers how API keys work, how to manage them, and security best practices.

API key format

OneHazel API keys follow the format:

oh_live_<64 hex characters>

For example: oh_live_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

The oh_live_ prefix makes keys easy to identify in code and logs. Keys are 32 random bytes (256 bits of entropy) encoded as hexadecimal.

Using your API key

Include your API key in the Authorization header as a Bearer token:

curl https://api.onehazel.com/operator-data-api/settings \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

All API endpoints use this same header format.

Creating API keys

Via the dashboard

1. Navigate to Settings > API Keys in the OneHazel dashboard
2. Click Create API Key
3. Give it a descriptive label (e.g. "Production backend", "Staging ETL")
4. Copy the key immediately — it is only shown once

Via the API

curl -X POST https://api.onehazel.com/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "operatorId": "your-operator-id",
    "label": "Production backend"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key": "oh_live_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "label": "Production backend",
    "createdAt": "2026-04-06T12:00:00.000Z"
  }
}

Listing API keys

curl https://api.onehazel.com/api-keys \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Keys are returned with masked hashes — the plaintext key is never stored or retrievable after creation.

Renaming a key

curl -X PATCH https://api.onehazel.com/api-keys \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "New label"
  }'

Revoking a key

curl -X DELETE "https://api.onehazel.com/api-keys?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Last-key guard

You cannot revoke your last active API key. Create a new key before revoking the old one. This prevents accidental lockout.

Hard deleting a key

Already-revoked keys can be permanently deleted:

curl -X DELETE "https://api.onehazel.com/api-keys?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&hard=true" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Active keys must be revoked before they can be hard-deleted.

Security

Key storage

API keys are never stored in plaintext. OneHazel stores only the SHA-256 hash of each key. When you authenticate, the provided key is hashed and compared against stored hashes.

Key rotation

Best practice is to rotate keys periodically:

1. Create a new key
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key

JWT sessions (dashboard only)

The OneHazel dashboard uses Supabase JWT sessions for browser authentication. JWTs are resolved to operators via user_profiles.actor_id. JWT auth is for the dashboard only — all programmatic API integrations should use API keys.

Rate limits

Rate limits are applied per operator, per endpoint category:

Endpoint Category	Limit
Data ingestion (realtime)	Standard rate limit
Data ingestion (batch)	Standard rate limit
Gateway execution	Standard rate limit
Analytics read	200 requests / minute
Analytics export	5 requests / minute
Analytics refresh	1 request / minute

When rate-limited, the API returns HTTP 429 with a Retry-After header and a resetAt timestamp in the response body.

Error responses

HTTP Status	Error Code	Description
401	AUTH_MISSING	No Authorization header provided
401	AUTH_INVALID	API key not recognised
401	AUTH_REVOKED	API key has been revoked
429	RATE_LIMITED	Too many requests — check Retry-After header