Authentication and scopes

Secret and publishable keys, the scopes a key can hold, IP and rate limits, and what needs a signed-in user.

Embed
Preview of the card
<a href="https://hermeticor.com/guides/api-keys"><img src="https://hermeticor.com/guides/_api/public/orgs/5fcd8b3c-a27c-4688-972f-de710125592f/spaces/9a3da731-ded5-4536-b84f-8c9a61420ff4/pages/3a820e7d-d8a0-4bf2-9106-1039b0cd38cb/social-card.svg?v=3e7ae33eec8b" alt="Authentication and scopes" width="600" height="315"></a>

Every API call carries a key as a bearer token:

curl -s "$BASE/v1/workspace" -H "Authorization: Bearer $HERMETICA_API_KEY"

BASE is https://hermeticor.com. A key belongs to one workspace.

Two kinds of key

Kind

Prefix

Use it from

Can do

Secret

hm_sk_

Your servers

What its scopes allow

Publishable (site key)

hm_pk_

Browsers and mobile apps

Send events and form submissions only

Create secret keys in the web app under Settings → API keys. Site keys can be made there under Settings → Sites, or with a secret key that has api_keys:write:

curl -s -X POST "$BASE/v1/sites" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Marketing site","domain":"example.com"}'

The answer holds the site key (plaintext, shown once). GET /v1/sites lists them and DELETE /v1/sites/<id> revokes one. A key can never create a secret key.

The secret is shown once. Keep it in a secret manager, never in a browser or a repository. If one leaks, revoke it under Settings → API keys; it stops working at once.

Scopes

Each area has a :read and a :write scope: profiles, events, segments, campaigns, workflows, templates, connections, consent, analytics, settings, members, api_keys, audit, outbound, forms, integrations, messages, newsletter, mkt_events (webinars and other events).

Extra scopes for actions:

Scope

Allows

messages:send

Transactional and one-off sends

campaigns:send

Sending or scheduling a campaign

campaigns:approve

Approving or rejecting a campaign or a template version

workflows:edit

Editing journeys

ingest:write

Sending events

mcp:use

The MCP server

embeds:write

Embeddable cards and editors

Give each key only what it needs. A call outside a key's scopes answers 403 with Missing scope x:y.

Limits

  • IP addresses. A key can be limited to a list of addresses.

  • Rate. Every key is limited to 1,200 requests a minute unless you give it its own requests-per-minute limit (set a lower one on keys you hand to third parties). Each response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Over the limit, you get 429 with Retry-After.

What needs a signed-in user

Some actions need a person signed in to the web app, not a key: creating secret keys, registering OAuth clients, inviting members and changing roles, agency tools, and lifting hard-bounce suppressions. With a key they answer 403 and say a user session is needed.

Check the API is up

GET /healthz and GET /readyz need no key.

Updated