API Authentication
Authenticate with the EngageTrack API using API keys.
API Authentication
All EngageTrack API requests are authenticated using API keys. API keys provide scoped, long-lived access and are designed for server-side integrations, CI/CD pipelines, data warehouses, and automation workflows.
Getting an API Key
- Navigate to Settings > API Keys in your dashboard
- Click Create API Key
- Enter a descriptive name (e.g.,
Data Warehouse Sync) - Select the scopes your integration needs
- Optionally set an expiration date
- Click Create and copy the key immediately
The full API key is shown only once at creation. Copy it and store it securely — in a secrets manager or environment variable. If you lose it, you must revoke the key and create a new one.
API keys require a Startup plan or higher. See Plans & Pricing for details.
Using an API Key
Pass the key as a Bearer token in the Authorization header of every request:
curl https://api.engagetrack.net/api/v1/organizations/{orgId}/sites \
-H "Authorization: Bearer et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"Key Format
API keys follow the format et_live_ followed by 32 hexadecimal characters:
et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Scopes
API keys are granted specific scopes that control which endpoints they can access. Assign only the scopes your integration needs.
| Resource | Scope | Grants access to |
|---|---|---|
| Analytics | analytics:read | Stats, charts, pages, sources, devices, locations, revenue, channels |
| Sites | sites:read | List sites and get site details |
| Goals | goals:read | List goals, goal stats, and goal completions |
| Goals | goals:write | Update and archive/unarchive goals |
| Funnels | funnels:read | List funnels and view funnel analysis |
| Funnels | funnels:write | Create, update, and delete funnels |
| Annotations | annotations:read | List annotations |
| Annotations | annotations:write | Create and delete annotations |
| Visitors | visitors:read | List visitors and view visitor timelines |
Write scopes do not imply read access. If your integration needs to both read
and write goals, assign both goals:read and goals:write.
Limits
- Maximum 10 API keys per organization
- API keys grant access to data endpoints only (analytics, goals, funnels, annotations, visitors, sites)
- API keys cannot access management endpoints (billing, team, integrations)
- Rate limits apply per-key — see Rate Limiting
Expiration
API keys can have an optional expiration date. Expired keys return 401 Unauthorized. We recommend setting an expiration and rotating keys periodically.
Security Best Practices
- Use minimal scopes. Only assign what your integration actually needs.
- Set an expiration date. Avoid keys that live forever. Rotate before expiry.
- Store keys securely. Use environment variables or a secrets manager. Never commit API keys to version control or embed them in client-side code.
- One key per integration. If one integration is compromised, you can revoke it without affecting others.
Error Responses
401 Unauthorized
{ "error": "Invalid or expired API key" }The key does not exist, has been revoked, or has expired.
402 Payment Required
{ "error": "API key access requires a Startup plan or higher" }Upgrade your plan at Settings > Billing.
403 Forbidden
{ "error": "API key missing required scope: analytics:read" }The key lacks the scope needed for this endpoint. Create a new key with the correct scopes.
For full key management (creating, listing, and revoking keys) see the API Keys guide.