API Keys

Create and manage API keys for programmatic access to your analytics data.

API Keys

API keys let you access EngageTrack data programmatically without a user session. They are ideal for server-side integrations, automated reporting, data warehouse syncs, and CI/CD pipelines.

API keys require a Startup plan or higher. Organizations on the Maker plan will receive a 402 error when attempting to create a key.

Creating an API Key

Via the Dashboard

Go to Settings > API Keys
Click Create API Key
Enter a name and select scopes
Click Create and copy the key immediately

The full key is shown only once. Store it in a secure location such as a secrets manager or environment variable. If you lose it, you must revoke the key and create a new one.

Via the API

You can also create API keys programmatically. Key management endpoints require a user session token — obtain one by logging in via the dashboard or the /api/v1/auth/login endpoint.

curl -X POST \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/api-keys' \
  -H 'Authorization: Bearer <session_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Data Warehouse Sync",
    "scopes": ["analytics:read", "sites:read"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response includes the full key in the key field. This is the only time the full key is returned.

Scope Reference

Scopes control which API endpoints a key 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, and all other analytics breakdowns
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.

Usage Examples

All examples use the base URL https://api.engagetrack.net/api/v1.

Get site analytics stats

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/sites/{siteId}/analytics/stats?period=30d' \
  -H 'Authorization: Bearer et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'

Required scope: analytics:read

List all sites

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/sites' \
  -H 'Authorization: Bearer et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'

Required scope: sites:read

Export page analytics

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/sites/{siteId}/analytics/pages?period=30d&limit=100' \
  -H 'Authorization: Bearer et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'

Required scope: analytics:read

List visitors

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/sites/{siteId}/visitors?page=1&limit=50' \
  -H 'Authorization: Bearer et_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'

Required scope: visitors:read

Security Best Practices

Use minimal scopes. Only assign the scopes your integration actually needs. A reporting dashboard only needs analytics:read and sites:read.
Set an expiration date. Avoid creating keys that live forever. Set a reasonable expiration (e.g., 90 days) and rotate before it expires.
Store keys securely. Use environment variables or a secrets manager. Never commit API keys to version control or embed them in client-side code.
Rotate keys regularly. Create a new key, update your integration, then revoke the old key. This limits the impact of a leaked key.
Use one key per integration. If one integration is compromised, you can revoke its key without affecting others.
Monitor usage. Review your active API keys periodically in Settings > API Keys and revoke any that are no longer in use.

Rate Limits

API key requests are rate-limited per key. Analytics endpoints allow up to 600 requests per minute. If you exceed the limit, the API returns 429 Too Many Requests with X-RateLimit-* headers indicating when you can retry.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Error Responses

401 Unauthorized — Invalid or expired key

{
  "error": "Invalid or expired API key"
}

The key does not exist, has been revoked, or has expired. Create a new key if needed.

402 Payment Required — Subscription required

{
  "error": "API key access requires a Startup plan or higher"
}

Your organization is on the Maker plan, which does not include API access. Upgrade to Startup or Agency at Settings > Billing.

403 Forbidden — Missing scope

{
  "error": "API key missing required scope: analytics:read"
}

The key does not have the scope needed for the requested endpoint. Create a new key with the correct scopes.

429 Too Many Requests — Rate limited

{
  "error": "Rate limit exceeded. Retry after 2026-03-14T12:01:00Z"
}

Back off and retry after the time indicated in the X-RateLimit-Reset header.

Managing API Keys

Listing Keys

View all active API keys in Settings > API Keys, or via the API (requires session token):

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/api-keys' \
  -H 'Authorization: Bearer <session_token>'

The list shows each key's name, scopes, creation date, expiration, and a masked preview of the key (last 4 characters only).

Revoking a Key

Revoke a key from the dashboard by clicking the Revoke button, or via the API (requires session token):

curl -X DELETE \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/api-keys/{keyId}' \
  -H 'Authorization: Bearer <session_token>'

Revoked keys stop working immediately. This action cannot be undone.