API keys and scopes

An API key authenticates a script or integration as your account against the platform API (/api/v1/). Create a key from your account settings, then send it in the Authorization: Bearer header of every request.

Creating and managing keys

Create a new key on your account settings page under API keys. Name the key so you can tell which integration holds it, and copy it immediately when it appears—it is displayed exactly once and is never retrievable afterwards, because only its SHA-256 hash is stored. The key begins with the prefix ep_live_ and functions like a password: store it in a secrets manager, never commit it, and replace it if anyone else has seen it.

The key list shows each key's name, its first 12 characters (ep_live_ plus four characters, enough to identify it) and a last-used timestamp; the secret itself never appears. The last-used timestamp is written at most once every five minutes, so it is an activity indicator, not a precise audit log.

Keys do not expire. Revoking one takes effect immediately—the next request presenting it gets 401. There is no per-account limit on how many keys you hold.

Security: keys carry full account access

An API key resolves to the wildcard scope *, so it passes every scope check. A key cannot be narrowed: there is no way to create a read-only key, a webhooks-only key, or a key scoped to one document. Any key can read and write files, manage webhooks, read readership data, and read your account profile. Every scope EveryPage adds in future is held by all existing keys automatically, with no further consent step.

If different integrations need different permissions, use OAuth instead. An OAuth access token holds only the scopes granted at authorization time—an app that displays readership can hold only readership:read, while a document-capture automation holds only files:write. OAuth tokens are narrowed by scope; API keys never are.

Understanding scopes

Scopes gate individual endpoints. EveryPage defines five:

These names apply to OAuth tokens, which hold only the scopes granted at authorization. API keys hold * and satisfy all five—the table describes what a key can reach, not a choice you make when creating one.

Rate limits

Requests to /api/v1/ are limited to 120 per minute, keyed on the value of the Authorization header. That means the bucket is per token, not per IP: integrations sharing an egress IP do not share a budget, and two keys on the same account get a budget each. Over the limit the API returns HTTP 429.

Two exceptions:

• POST /api/v1/webhooks/{uuid}/test carries an additional 10-per-minute limit on the same per-token key, because each call fires a synchronous outbound request.
• The /api/v1/canva/* endpoints are not bearer-authed and are limited per IP instead.

Plan-based endpoint access

API keys are available on every plan, including free. Creating a key has no plan check.

Individual endpoints still enforce their own plan requirements, and a key never lifts them: /events?type=gate and /gate-responses require Pro, per-page readership requires Basic or higher. A request below the required plan returns HTTP 403 with a plain-text body such as This feature requires the pro plan or higher.

Viewing the API reference

The full OpenAPI schema is published at /openapi.yaml (YAML). Swagger UI, Postman, VS Code REST Client, and SDK generators all accept it by URL. The developers page lists the available operations.

Next steps

• Authentication — learn how Bearer tokens work and how to add them to requests
• OAuth and oEmbed — create OAuth apps for narrowed permissions
• Webhooks — subscribe to events via API
• Events feed — stream view sessions, downloads, and gate responses
• Plans and limits — see which features require each plan