Endpoint scope map

This page is the source of truth for what an API key can and cannot reach. Every route in the backend falls into one of three buckets:

• API key accepted: works with both a JWT (dashboard user) and an API key with the listed permission.
• JWT only: never reachable via an API key. Used for billing, governance, websocket bootstrap, danger-zone destruction, the OAuth onboarding flow, and admin tools.
• Public: no auth required (webhooks with signature verification, health check, OAuth bouncer pages).

When an endpoint says "JWT permission: X / API permission: Y", the dual-auth middleware checks the relevant one based on which credential the caller used.

All paths below are relative to the versioned base URL https://api.warmbly.com/v1 (for example /campaigns is https://api.warmbly.com/v1/campaigns). See versioning for details.

API key accepted

Emails

Campaigns and sequences

Campaigns, steps and activity logs are scoped to the selected organization for session callers and the key's organization for API-key callers. Access depends on the permissions below, regardless of who created the campaign. Step updates and deletes also require the step to belong to the campaign in the URL. Campaign analytics, including daily, hourly and comparison endpoints, use this same organization boundary and require READ_ANALYTICS (or View analytics for session callers).

The hold, pause and resume calls under /campaigns/:id/leads/:contactId/ hold one contact's flow inside one campaign: an out-of-office auto-reply writes one automatically, and a member can write one by hand. The contact stays subscribed and stays a lead, so this is not an unsubscribe and not a suppression. Both writes state an absolute hold rather than applying a delta, and replacing a live hold keeps its original start, so a retry lands on the same row and neither needs an Idempotency-Key. See pause a lead.

The cc calls under the same path set the contacts copied on every email to one lead. Their answers carry contact names and addresses, so they need contact read access as well as the campaign scope. PUT sends the whole list, so a retry lands on the same state and needs no Idempotency-Key. See set a lead's CC.

GET /campaigns/:id/forms reports the forms this campaign links to and what its recipients did with them: personalized links handed out, who opened one, who started filling it in and who submitted. See the forms guide.

GET /campaigns/:id/send-plan returns today's sending plan: what the campaign is expected to send, and every limit that decided the number. For an active campaign the plan is computed in the background and served from a stored snapshot, so the read stays fast on a campaign of any size. computed_at is when that snapshot was walked, and stale is true when the campaign has since been edited, started, stopped, or has crossed into a new budget day and a refreshed plan is already being computed: the figures are the last good ones and a current plan follows within moments. A campaign that has no snapshot yet (a brand-new one) is computed on the request instead. See the send plan guide.

/email-images is the workspace's image library for email bodies. POST takes a multipart file field (PNG, JPG, GIF or WebP, up to 5 MB) and returns the row with the public url you put in an <img src>; those bytes count against the same storage quota as campaign attachments. GET is keyset-paginated newest first (?limit= 1 to 100, ?cursor= the opaque pagination.next_cursor). DELETE removes the object before the row and refuses with a 503 if storage will not take the delete, so a failed call changes nothing and can be retried; once it succeeds, an image in mail already sent stops loading.

Contacts

GET /contacts/custom-fields lists the distinct custom-field keys used across your contacts (frequency-ranked), for building personalization pickers and import column mappers. It returns a flat string array under data, capped at 200 keys.

The import pair is two steps over the same file: preview parses it and suggests a column mapping (matching headers to your existing custom fields), commit applies the mapping you chose. Commit takes the stricter BULK_CONTACTS scope because one call writes up to 50,000 rows. A mapping problem, an unusable custom-field name or no email column, is a 400 on the whole request; see contacts.

AI contact research charges credits (2 per run, billable even when it finds nothing) and only saves cited findings. See the AI contact research guide. The batch endpoint accepts up to 500 contact ids and drains in the background.

Segments

Segments are saved contact audiences: a condition list plus per-contact manual overrides, evaluated live. Contact scopes cover them because a segment is a view over contacts; enrolling one into a campaign writes leads, so that call takes the campaign write scope, as does managing a campaign's linked segments (/campaigns/:id/segments above). POST /contacts/search and POST /contacts/export accept segment_ids to scope any contact query to a segment. See contacts for the condition format.

Forms

Hosted lead-capture forms; see the forms guide. Contact scopes cover them because a form exists to create contacts. Minting a personalized link is a GET on top of an upsert, so retries always return the same token. The /forms/domain routes are the workspace-wide custom forms domain and additionally need the manage_settings organization permission for JWT callers; PUT resolves the record as part of saving, and only a verified domain is ever used to build a URL. The public page (/f/:public_id), its submit endpoint and the embed loader (/forms.js) are served by the standalone forms service on its own host (FORMS_DOMAIN), not the API origin, and take no authentication; the unguessable public id is the capability, and the JSON endpoints additionally require the render token the page shell carries.

Lead sync

Saved Google Sheets sources that upsert contacts on demand. Gated under the contact write scope because a sync ultimately writes contacts. Nothing syncs on a timer: a source only runs when /lead-sync/sources/:id/sync is called.

A source's column_mapping is validated when the source is written, not on its next sync, so a mapping with no email column or an unusable custom-field name is a 400 on create or update. See integrations.

Unibox

PATCH /unibox/folder re-files into inbox, archive or trash. Name the messages with email_ids, the conversations with thread_ids, or both; up to 500 of each. Prefer thread_ids when you have one: filing part of a conversation leaves it listed, because a thread shows wherever any message of it still sits. The move is then relayed to each mailbox with relay_folder_moves on (the default): the provider's copy is archived, moved to its trash, or put back in its inbox, after the response and best-effort, and the next sync will not undo a filing either way, because the provider's placement is tracked separately and followed only when the provider itself moves the message. sent, drafts and spam are placements a provider reaches rather than somewhere a person files mail, so they are rejected with a 400. See filing a conversation.

PATCH /unibox/seen takes the same two forms: email_ids for individual messages, thread_ids for whole conversations. folder sweeps one folder instead and cannot be combined with either. Unread by conversation marks only its newest received message (preferring one outside spam and trash), or its newest sent copy if it has no received message; otherwise sent copies stay read. Drafts are never marked unread. Explicit email_ids and folder sweeps never mark sent or draft copies unread.

GET /unibox lists every working folder by default. Spam, trash and archive stay out, so a conversation you file leaves every view rather than only the Inbox folder; pass include_archived=true for the All mail behaviour, or folder=archive to read the folder itself.

POST /unibox/snooze accepts thread_id for one conversation or thread_ids for up to 500. The single form answers with the snooze row, as before; the bulk form answers with data. DELETE /unibox/snooze?thread_id= accepts a comma-separated list.

POST /unibox/reply with forward_message_id forwards a stored message, which discloses it, so the key also needs READ_UNIBOX and, when it is restricted to certain mailboxes, the mailbox the message belongs to. See Forwarding a message.

POST /unibox/reply/draft returns an AI-drafted reply (it never sends) grounded in the thread, the contact, and your voice profile. It charges AI credits; see AI credits.

POST /unibox/compose/draft returns a grounded AI draft for a new email (it never sends): the recipient's contact record, correspondence history, and the workspace voice profile feed the prompt, and the response carries either text or a clarifying question plus a grounding report. Charges AI credits like the reply draft; see AI credits.

POST /unibox/compose sends a brand-new outbound email (not a reply). body_html goes out as written; with body_plain left empty, the plain-text part is rendered from it, which POST /unibox/reply does too. Omit email_account_id (or pass "auto") and the backend picks the best mailbox for the first recipient; the response reports account_id, account_email, auto, and a picked_reason. Recipients on the workspace suppression list are rejected with a 400 before anything queues. GET /unibox/compose/candidates?to=<address> returns every active mailbox scored for that recipient (conversation history, remaining daily budget, domain-auth health) plus the resolved contact and suppression state; see composing email.

The /unibox/drafts endpoints hold autosaved compose drafts, scoped to the calling user within the organization. The draft id is client-generated, so PUT is idempotent (safe for debounced autosave and retries); deleting a missing draft is a no-op. A draft carries body (the plain text) and body_html, which is empty for a plain-text draft; each is capped at 100,000 characters.

GET /emails/:id/auth-check runs a live SPF/DKIM/DMARC lookup on the mailbox's sending domain and reports it without changing anything. POST /emails/:id/auth-check runs the same lookup and records the verdict against every active mailbox on that domain, which is what clears the send gate after a DNS fix, so it needs WRITE_EMAILS rather than READ_EMAILS. The write takes no Idempotency-Key: it is derived entirely from public DNS with no request body, so repeating it converges on the same result. See domain authentication.

GET /emails/:id/track reports the mailbox's stored tracking domain plus the CNAME value this deployment expects (cname_target, taken from its TRACKING_DOMAIN), and does no DNS work. PATCH /emails/:id/track sets the domain and resolves it once; POST /emails/:id/track/verify re-resolves the saved one and records the verdict, which is what makes a record that has finished propagating start being used. Both writes are derived from public DNS with no request body, so they take no Idempotency-Key. Only a verified domain is used at send time; until then opens and clicks go through the shared tracking host. See custom tracking domain.

POST /emails/:id/hold keeps a mailbox out of campaign sending until POST /emails/:id/release puts it back; warmup is unaffected and the automatic rest logic never releases a hold. release is also the manual exit for a mailbox that is resting automatically. Both are bodyless and idempotent, so they take no Idempotency-Key. See holding a mailbox yourself.

GET /emails/allowance reports how many mailboxes the workspace holds (used), how many it may hold (allowance, null for unlimited), remaining, and the basis of the number: fair_use (the plan's daily sends divided by sends_per_mailbox), plan, override (an approved request), free, or unlimited. pending_request is the open limit-increase request for mailboxes, if any. Every connect path refuses with mailbox_allowance_reached once remaining is 0. See mailbox allowance.

GET /emails/:id/identity reports which addresses the mailbox's provider will let it send as, which one it uses, and whether its signature was imported or written here; it contacts no provider. POST /emails/:id/identity/refresh re-reads that list from the provider and stores it, and with import_signature also replaces the stored signature with the one configured at the provider. Storing the list is what a send_as_email choice is validated against, so the refresh needs WRITE_EMAILS rather than READ_EMAILS; it takes no Idempotency-Key because it writes exactly what the provider currently says. Gmail only. See sending identity.

GET /emails/:id/sync reports, alongside the import state and budget, skip_folders (the folders the mailbox's sync leaves alone) and folders (what the worker last listed on the server, each with its name and the canonical folder it files under, INBOX first; empty for Gmail and Outlook). PUT /emails/:id/sync takes {"skip_folders": [...]} and replaces the list: names as the server lists them, matched without regard to case, each covering its subfolders. Mail already stored from a newly skipped folder is removed, the mailbox is re-shipped to its worker so the change applies on the next pass, and the response is the list as stored. It refuses INBOX and any sent, drafts, spam, trash or archive folder with 400 invalid_sync_folder, as it does a list of more than 50 names or a mailbox that is not IMAP. The body is the desired state, so it takes no Idempotency-Key. See folders you do not want synced.

PATCH /emails/:id accepts save_to_sent (boolean) on SMTP/IMAP mailboxes: when true, which is the default, the worker files a copy of each outbound message in the mailbox's Sent folder. It has no effect on Gmail and Outlook mailboxes, whose APIs file their own copy. See keeping a copy of sent mail.

PATCH /emails/:id also accepts relay_folder_moves (boolean, default true), on every provider: when true, filing a conversation with PATCH /unibox/folder moves it in the mailbox too. See filing in the mailbox.

DELETE /emails/:id releases the mailbox on Warmbly Cloud before removing the local mailbox. An enrolled mailbox's stored credential comes out of the pool, and a cloud-managed mirror's claim is released so the mailbox returns to the cloud workspace and can be adopted again. If the cloud cannot confirm the release, the delete returns 409 mailbox_cloud_unenroll_failed and keeps the mailbox record so the request can be retried safely. Warmbly attempts to restore the mailbox onto its worker immediately, and the worker reconciler may restore it later if that attempt fails. See mailboxes.

GET /unibox and GET /unibox/thread return message previews: each row carries snippet, a one-line summary, not the message body. Read a full message with GET /unibox/:id, which returns body_plain plus body_html. The HTML is sanitized before it leaves the API (scripts, event handlers, embedded frames, and unsafe URL schemes are removed), so it is safe to render, and links carry target="_blank" with rel="noopener". Warmbly open-tracking pixels are also removed from this display copy, including quoted history, so rendering it does not record a campaign open. Stored and delivered copies keep their pixels. body_truncated is true on the rare message whose stored body could not be read, where body_plain falls back to the snippet. The same response carries the full envelope (from, to, cc, bcc, ReplyTo, date, internal_date, message_id, in_reply_to, size), the mailbox it belongs to (email_id) and its canonical folder.

GET /unibox also accepts address=<value> (matches sender or recipient, for "every conversation with this person") and direction=sent|received (resolved against your own mailbox addresses).

The agent-drafts endpoints back the inbox agent: the agent drafts a suggested reply on an inbound human reply and holds it here for review. GET lists the pending drafts; approve sends one (optionally with an edited body) through the normal reply path and is safe to retry with an Idempotency-Key; discard dismisses it. Approving is the only path that sends.

Templates and CRM

The /crm/settings through /crm/lists routes are CRM provider mode (HubSpot or Pipedrive), and act on the CRM the workspace runs on. For a dashboard session they gate on view_contacts to read, manage_contacts to edit a contact's CRM record or import a list, and manage_settings to change the mode, match owners, run a sync or copy records. POST /crm/sync/retry, POST /crm/sync/discard and POST /crm/backfill are naturally safe to retry: a requeued job is not queued twice and a copied record is never copied again. While HubSpot or Pipedrive is the workspace's CRM, writes to pipelines, stages and task types answer 409 crm_managed_externally. See CRM.

Analytics and audit

Analytics reads use the selected workspace for JWT callers and the key's workspace for API-key callers. This includes warmup and usage totals, so teammates see the same workspace history regardless of which member connected a mailbox or created a campaign.

GET /analytics/inbox-tagging accepts limit, opaque cursor, and needs_review query parameters and returns data, aggregate summary, and pagination. Each row carries actions, the list of what the verdict was allowed to do (hold, stop, task, suppress), and summary.acted counts the rows that did anything. return_date (YYYY-MM-DD, or null) is the out-of-office return date the model was asked to confirm, with its answer under answers.return_date. Invalid cursors, limits, or booleans return 400.

GET /analytics/accounts returns account health and usage in the standard data plus pagination envelope with an opaque cursor. Pass email_ids (comma-separated, up to 200) to ask only for the mailboxes a page shows, or limit (1-1000, default 1000) and cursor to walk the whole inventory. Per-mailbox reads are batched across the page, so a page's cost does not grow with the total inventory, and a workspace with more mailboxes than one page reaches the rest through next_cursor instead of having them silently dropped. Invalid cursors, limits, or ids return 400.

Inbox placement tests

A placement test sends real mail from one of the workspace's mailboxes, so starting and cancelling one takes the same permission as starting a campaign, while reading results is an analytics read. Everything here is scoped to the workspace: a test, a sending mailbox, a campaign, a step and a contact are each checked to belong to it before anything is sent.

For session callers the matching organization permissions are View analytics for the reads (tests, batches, a batch's senders and coverage), Send campaigns for starting, previewing and cancelling a test or a batch, View campaigns for listing seed inboxes and Manage mailboxes for marking one. The campaign's placement monitor (/campaigns/:id/placement-monitor, listed under campaigns above) is read with View campaigns and changed with Send campaigns.

A key restricted to certain mailboxes can only start a test from one of them and only sees and marks those mailboxes as seeds. POST /placement/tests accepts an Idempotency-Key; PUT /placement/seeds/:email_account_id and PUT /campaigns/:id/placement-monitor state an absolute value, so a retry lands on the same state. GET /placement/tests takes limit (1 to 100, default 25), an opaque cursor and an optional campaign_id, and returns data plus pagination; an invalid cursor or limit is a 400. It leaves out the tests a batch started, which are read through their batch.

A placement batch runs the same test from many mailboxes. POST /placement/batches takes the copy, panel, tracking and pace a single test takes, plus exactly one of sender_account_ids or sender_scope ({"type": "campaign", "campaign_id": ...} or {"type": "workspace"}, with optional providers, domains, tag_ids, include_inactive and untested_days), an optional sample, on_unavailable (defer or skip) and max_credits for the whole batch. It answers 201 with the batch queued as soon as the senders are written down; the backend starts them a few at a time. POST /placement/batches/preview takes the same body and returns the counts it would come to (senders, tests, the most copies sent, free and paid tests, credits) without starting anything or writing a row. A key restricted to certain mailboxes can only name those in sender_account_ids (another is a 403), and a server-side scope resolves to those alone. POST /placement/batches accepts an Idempotency-Key; cancelling states an end state, so a retry answers placement_batch_not_running and changes nothing. GET /placement/batches and GET /placement/batches/:id/senders take limit and cursor like the tests list; the senders list also takes sort (worst, the default, best, email or status), status and q (a substring of the address), and an unknown value of any of them is a 400. See the placement endpoint reference.

Advisor

Recommendations about deliverability, mailbox configuration, warmup, campaign performance, copy, and list quality. See the Advisor guide.

Reads are an analytics read of the workspace's sending posture. Applying or undoing a fix has no scope of its own: the change runs through the tool the fix actually uses and is refused if the caller lacks that tool's permission, so a key that can read recommendations cannot use them to make changes it could not make directly.

Apply and undo run the fix under the key's own scopes, and a key limited to certain mailboxes can only apply or undo a fix for one of them (403 otherwise). Changing Advisor settings (PATCH /advisor/settings) is JWT only, alongside the rest of organization settings. Silencing checks for a whole workspace is governance, and no read scope should be able to do it. The same applies to POST /advisor/recommendations/:id/agent-fix, which is JWT only and needs USE_AI: it acts as a named member and spends credits, and no API scope should let a key rewrite a workspace's campaigns unattended.

API key self-service

DELETE /api-keys/:id/permanent deletes a key that has already been revoked or has expired, taking its usage logs with it. A key that could still authenticate gets a 409, because revoking is what records that a credential was ended and why. See Ending a key.

POST /api-keys requires a recent confirmation (POST /auth/reauth) when called from a signed-in session, because a key outlives the session that made it and a stolen browser token should not be able to leave one behind. An API key calling it is unaffected: it has no session and no second factor to present, it was itself minted from a confirmed session, and the API_KEYS scope is the explicit grant that governs it. Automation and the CLI keep working.

Creating, editing, revoking and deleting keys is for a signed-in member or an API key; an OAuth app token gets 403 oauth_token_not_allowed. A new or edited key stays within its creator: a member cannot give it a permission their role does not cover, and an API key cannot give it a permission, mailbox or IP address the calling key does not have (403 api_key_permissions_exceed_caller). See what a role can delegate. GET /api-keys/permissions reports the caller's bound as grantable.

DELETE /api-keys/self revokes the key the request was made with, and is the one route here that needs no scope. A credential must always be able to end itself: requiring API_KEYS to sign out would leave a read-only key on a laptop someone is handing back live, which is what warmbly auth logout promises to prevent. A JWT caller gets a 400: there is no key in that request to end, only a session, which POST /auth/logout ends.

OAuth apps

Registering and managing the OAuth apps your workspace owns. The flow itself (authorize, token, revoke) is listed under JWT only and Public below. Every route here, and POST /oauth/application-logo, refuses an OAuth app token with 403 oauth_token_not_allowed.

The listing routes publish an app to the community directory. PUT replaces the whole listing and DELETE succeeds when there is nothing to remove, so both are safe to retry. Browsing the directory is GET /integrations/community and GET /integrations/community/:slug, under /integrations/* below.

Operations

A signed-in member needs manage_settings to create, edit, enable or delete an automation, because a flow runs as the workspace; use_integrations is enough to list, open, test and read the run history. | GET/POST/PATCH/DELETE | /warmup/routing[/:id] | WARMUP_ROUTING |

Retry safety

Mutating API requests may include an Idempotency-Key header. Warmbly stores the completed response for 24 hours per organization and key. Reusing the same key with the same method, route, query, and body replays the original response with X-Idempotent-Replayed: true; reusing the key with a different request returns 409 Conflict.

Identity

GET /me returns who the active credential belongs to: user_id, email, name, organization_id, organization_name, auth_type (api_key, oauth, or jwt), and the granted scopes. It requires no specific permission, so it is the right call for validating a connection and rendering a human-readable label. Unlike /auth/me (JWT only), it is reachable by API keys and OAuth tokens.

Labels

Folders (on campaigns), tags (on mailboxes) and labels (on contacts, inbox conversations and forms, managed through the /categories endpoints) are three registries with the same shape. Each belongs to the workspace, not to whoever created it. Every member sees the same set, whoever created it, and reads it from GET /auth/me, which returns folders, tags and categories for the session's selected workspace; there is no separate list endpoint and no read scope of its own. Changing a registry is gated like the records it labels, so it takes the API permission in the table below, or the matching JWT permission MANAGE_CAMPAIGNS, MANAGE_EMAILS or MANAGE_CONTACTS. Membership alone is read-only.

position is the order within its own registry, 0-based and contiguous. A move returns the full new ordering. A registry holds at most 100 entries.

Reference data

JWT only

These never accept an API key. They depend on a human-bound session: billing flows, governance, OAuth onboarding, websocket bootstrap, and operational destruction.

With multiple dashboards sharing a backend, password-reset and invitation emails, referral links and billing returns use the initiating browser's exact configured dashboard origin. Without a trusted origin they use the primary dashboard. Mailbox, administrator-grant, integration and Slack identity OAuth callbacks recover their target from live server-side state, never from callback query parameters. Expired or consumed routing state is not forwarded to another dashboard.

• POST /auth/login, /auth/login/confirm, /auth/register, /auth/register/confirm, /auth/refresh, /auth/reset-password, /auth/reset-password/confirm
• POST /auth/reauth (re-prove the account holder behind a live session, for the changes that require a recent confirmation)
• GET /auth/config (public deployment capabilities: which sign-in methods this backend has enabled, whether a login code step follows, whether signups are open, whether the instance still needs claiming)
• GET /auth/instance (JWT only: the running Warmbly version of a self-hosted instance and whether a newer release exists, for the dashboard's version pill; a hosted deployment answers self_hosted: false and nothing else)

POST /auth/register accepts an optional invite field carrying an invitation token. On a deployment running DISABLE_REGISTRATION=invite_only it is what permits the signup, and the account is created inside the inviting organization rather than in a new one. The token must resolve to a live invitation whose email equals the submitted address, otherwise the request is refused with invitation_invalid. Omitting it on a closed deployment returns registration_invite_only or registration_closed. See error codes.

Actions that need a recent confirmation

These changes require the session to have confirmed the account holder within the last five minutes, over and above the permission they already need:

Each either hands out a credential that outlives the session that created it, reveals a secret, changes who can get in, cannot be reversed by the person it was done to, or reaches a whole domain's mail. Without a confirmation they answer 403 with code reauth_required; confirm with POST /auth/reauth (password or a current two-factor code) and retry. See error codes.

This applies to session callers. An API key or OAuth token has no session to confirm and is not the threat here, so it passes straight through to the route's permission gate.

A completed sign-in counts as a confirmation for the first five minutes of the session. An account with neither a password nor two-factor authentication has nothing else to confirm with, so after those five minutes POST /auth/reauth answers it 400 with code reauth_no_factor and it signs in again. Once 2FA is on, it confirms with an authenticator code like any other account.

GET /auth/config gained two fields: invites_required (boolean, true when an invitation token is needed to create an account) and docs_url (string, the deployment's link to the accounts and access documentation, for a client to surface next to a refusal).

GET /auth/config also carries websocket_url and app_url (both strings, each omitted when the instance has none). They are the realtime gateway a developer client connects to and the dashboard origin a client sends someone to. Both are served here because on a self-hosted instance the host layout is whatever the operator chose, and there is no other way to discover it: the CLI reads them for warmbly events tail and warmbly browse.

Alongside them, api_url is this API's own public base (for a copyable example that names the right server), and brand is who the deployment says it is: name, and website_url, website_label, terms_url, privacy_url and support_email, each omitted when unset. On a self-hosted instance that configured no EMAIL_BRAND_* only name is present, and a client should render no link at all rather than substituting one of its own. See configuration.

GET /auth/config also carries gmail_oauth_connect (boolean): whether a new Gmail mailbox may be connected with Google sign-in. Both BOX_GOOGLE_CLIENT_ID and BOX_GOOGLE_CLIENT_SECRET are required. With them set, the capability defaults to true; explicit BOX_GOOGLE_OAUTH_CONNECT=false or an invalid value disables it. When false, offer the app-password route (POST /emails/onboarding/smtp-imap against Gmail's servers) rather than start an OAuth round trip that returns mailbox_gmail_oauth_disabled. The dashboard additionally requires its deployment-local frontend opt-in to show Google sign-in. Existing Google sign-in mailboxes are unaffected either way.

GET /auth/config also carries billing_enabled (boolean). It is false when the deployment runs with BILLING_PROVIDER=none, which is the self-host default: every feature is unlocked server-side, so the dashboard shows the workspace as self-hosted instead of on a free trial and hides the billing and referral pages. self_hosted alone does not imply this, because a self-hosted install may still run Stripe.

• POST /auth/setup (first-run claim: exchanges the one-time token printed at boot for the owner account. Refused once any account exists)

• GET /auth/providers, POST /auth/apple, POST /auth/google (native-app social sign-in)

• POST /auth/oidc/begin, GET /auth/oidc/callback (generic OpenID Connect sign-in)

• POST /auth/google/begin, GET /auth/google/callback, POST /auth/apple/begin, POST /auth/apple/callback (browser Sign in with Google and Sign in with Apple)

• POST /auth/sso/exchange (swaps the single-use handoff code from any of those callbacks for the session; POST /auth/oidc/exchange is the older name for the same endpoint)

• POST /auth/sso/link (completes a provider sign-in that resolved to an existing password account: takes that account's password, attaches the identity and returns the session)

• POST /auth/logout, POST /auth/logout-all, GET /auth/me, PATCH /auth/me/onboarding

• POST /auth/me/avatar, DELETE /auth/me/avatar

• POST /emails/onboarding/oauth/start, POST /emails/onboarding/oauth/finish, POST /emails/onboarding/smtp-imap. oauth/start accepts an optional login_hint (an email address) that preselects that mailbox in the provider's sign-in, which is how an import's Sign in rows open. For Google and Microsoft dashboard flows (return: "web"), the browser's Origin is validated against exact configured dashboard origins and bound to the OAuth state; an untrusted origin answers 400 mailbox_oauth_return_origin. Requests without an Origin retain primary-dashboard routing while their state is live

• POST /emails/onboarding/smtp-imap/bulk (up to 50 SMTP/IMAP rows in accounts, answered 200 with a per-row status of connected, skipped or failed and a code; rows past the workspace's mailbox allowance fail with mailbox_allowance_reached before any credential is dialled. Naturally retry-safe: an already connected mailbox is skipped, so it takes no Idempotency-Key)

• The mailbox import routes under /emails/imports, all with JWT permission MANAGE_EMAILS. They carry passwords, so like onboarding they never accept an API key:

  • POST /emails/imports/preview: what an import of this input would do, row by row and domain by domain, without doing any of it
  • POST /emails/imports: store the rows and connect them in the background; answers 201 with the import
  • GET /emails/imports: the workspace's imports, newest first
  • GET /emails/imports/:id: one import with its counts and its failures grouped by cause
  • GET /emails/imports/:id/rows: an import's rows by line, filtered by status (comma-separated) and cause
  • PATCH /emails/imports/:id/rows/:line: correct one failed row (password, app_password, username, smtp, imap) and queue it again
  • POST /emails/imports/:id/retry: requeue failed rows, all of them or those with one cause or the listed lines, optionally with one new password for all
  • POST /emails/imports/:id/cancel: stop the rows not yet started; rows already connecting finish
  • POST /emails/imports/:id/dismiss: hide the import from GET /emails/imports for the workspace, stopping it first when it is still running. Its rows and history stay, and GET /emails/imports/:id still reads it. Answers 204; a repeat changes nothing
  • GET /emails/imports/:id/failed.csv: every row that did not connect, as uploaded minus passwords, with status, problem and how_to_fix

  Preview and create take multipart/form-data: file (CSV, TSV or XLSX up to 10 MB) or text (a pasted list), mapping (a JSON object of column index to field, such as {"0":"email","1":"password"}; omit it to use the automatic mapping) and options (JSON: has_header, shared_password, on_existing of update or skip, save_mapping, and settings applied to every mailbox). One import takes up to 5,000 rows. The two lists answer data plus pagination with next_cursor and has_more; limit is at most 100 for imports and 200 for rows, and a cursor that is not one this API issued returns 400 with invalid_cursor. None of these takes an Idempotency-Key. Repeating a create makes a second import, whose rows find the first one's mailboxes already connected and update (or skip) them, so nothing is connected twice. A retry only requeues rows that failed, and a fix is refused for a row that is not failed, so repeating either connects nothing twice. Cancelling an import twice is a no-op. Progress is published as the realtime event MAILBOX_IMPORT_PROGRESS; see realtime. Error codes are under mailbox import refusals

• Inbox vendor connections under /emails/vendors, JWT permission MANAGE_EMAILS. The key is sealed on the server and no response ever returns it:

  • GET /emails/vendors/catalog: the supported vendors, with each one's fields (key, label, secret, required, help) and key_help_url
  • GET /emails/vendors: the workspace's vendor connections with status, last_error and mailbox count
  • POST /emails/vendors: vendor, label and fields; the key is checked with the vendor first, answers 201. Repeating it makes a second connection
  • PATCH /emails/vendors/:id: rename, or replace fields after checking the new key with the vendor. Safe to repeat
  • DELETE /emails/vendors/:id: forget the key; the mailboxes it brought in stay connected. A repeat is a 404
  • GET /emails/vendors/:id/mailboxes: the vendor account's mailboxes, each marked connected when already in the workspace
  • POST /emails/vendors/:id/import: mailbox_ids or all, plus the same options as a file import; answers 201 with the import. Each call creates a new import; a repeat finds the first run's mailboxes connected and updates (or skips) them

• Admin grants under /emails/grants, JWT permission MANAGE_EMAILS. The four routes that record, use or remove a grant also need a recent confirmation:

  • GET /emails/grants/config: whether this instance takes Google and Microsoft grants, the Google google_client_id and google_scopes an administrator authorizes, and google_missing and microsoft_missing, the names of the instance settings still unset (empty when that provider is ready)
  • GET /emails/grants, GET /emails/grants/:id: grants with their provider, tenant, covered domains, status and mailbox count
  • GET /emails/grants/migration: the workspace's mailboxes on per-mailbox Google sign-in that can optionally switch connection methods, grouped by domain: data is a list of domain, kind (workspace, which moves onto an admin grant, or personal, a shared address such as gmail.com, which moves to an app password), grant_id when the workspace has an active Google grant covering the domain, and mailboxes (id, email, name, status); total counts the mailboxes. Mailboxes whose sign-in Warmbly Cloud holds are not listed. Read only
  • POST /emails/grants/google/start: domain and admin_email (on that domain). Answers how this workspace proves it controls the domain: method signin with a Google sign-in url and state (valid for 15 minutes) when the instance has a Google sign-in app, else method dns. Both carry txt_name (_warmbly.<domain>) and txt_value (warmbly-verify=..., unique to the workspace and domain), because the DNS proof always works. Safe to repeat
  • POST /emails/grants/google/finish (recent confirmation): either state and code from the Google sign-in, which must be admin_email itself on that domain, or domain and admin_email once the TXT record is published. The directory must list admin_email as a super administrator. Answers 201. A state is single-use; repeating a DNS finish re-verifies and updates the same grant, one per domain
  • POST /emails/grants/microsoft/start: the admin consent url and state for a Global Administrator, valid for 15 minutes
  • POST /emails/grants/microsoft/finish (recent confirmation): state and code from the consent callback; answers 201. The organization recorded is the one the administrator consented for, as the redeemed sign-in reports it. The state is single-use, so a repeat is refused with mailbox_grant_state_invalid. One grant per tenant: consenting again updates the same grant
  • POST /emails/grants/:id/check: verify now, and restart the grant's stopped mailboxes when it passes. Safe to repeat
  • DELETE /emails/grants/:id (recent confirmation): remove the grant; every mailbox it connected stops. A repeat is a 404
  • GET /emails/grants/:id/users: the granted directory, each user marked enabled and connected, with email_account_id when connected. upgrade is true for a user whose mailbox is already here on its own sign-in with the same provider (Google or Microsoft, not held by Warmbly Cloud): connecting it moves that mailbox onto the grant in place
  • POST /emails/grants/:id/connect (recent confirmation): user_ids or all (every enabled user not yet connected, plus every user marked upgrade), plus import options; answers 201 with the import. Each call creates a new import; a repeat finds the first run's mailboxes connected and updates (or skips) them. A user whose mailbox is already here as a delegated mailbox is relinked to this grant, and one on its own sign-in is converted onto the grant in place, keeping its history, campaigns and warmup, without counting against the mailbox allowance

• Sending domains under /emails/domains, JWT permission MANAGE_EMAILS. :domain is the bare domain:

  • GET /emails/domains: every domain the workspace sends from, with mailbox count, mail hosts, SPF, DKIM and DMARC, tracking hosts in use and the redirect. When a connected inbox vendor account holds the domain, vendor_domain carries vendor, connection_id, the current forwarding when the vendor reports it, can_forward, can_unforward, forwarding_reviewed (a change is applied later by the vendor's staff), can_dns and dns_types
  • POST /emails/domains/bulk: domains (1 to 100), tracking_label (one DNS label, such as link; each domain gets <label>.<domain>) and/or redirect_url, plus optional tracking_hosts and redirect_urls objects keyed by domain that give a listed domain its own host or website in place of the shared one. Each domain takes its vendor's path when the vendor's API can (writing the CNAME, forwarding the root) and is saved to wait for DNS otherwise. Optional served_by (instance or cloud) picks where a redirect no vendor forwards is served from; omitted keeps each domain's current choice. Answers data, one row per domain with tracking (host, via of vendor or dns, verified, mailboxes, cname_target, note when the vendor refused the record) and redirect (target_url, via of vendor, dns or cloud, verified, reviewed); a refused domain carries error and code on its row and never stops the others. Safe to retry: each setting is set, not added
  • GET /emails/domains/:domain/tracking-suggestion: the tracking host to offer, its status (active, found or suggested), the cname_target, and vendor_domain when a connected vendor account holds the domain
  • PUT /emails/domains/:domain/tracking: host for every mailbox on the domain (empty clears it); answers the verification result and the number of mailboxes changed. Idempotent
  • PUT /emails/domains/:domain/redirect: target_url, optional include_www (default true) and optional served_by (instance, or cloud on a self-hosted instance linked to Warmbly Cloud; omitted keeps the current choice, and a new redirect is served by this instance). Checks it once and answers the redirect with its records, served_by, serve_host (the tracking host that answers, which a proxy routes the domain to) and, once DNS verifies, reach: the last visit to the domain, with status (ok, not_reaching, https_error or unreachable), hint (not_routed, host_header, wrong_target, certificate, no_listener, or settling while the tracking service picks up a redirect that has just verified), a detail sentence, the proxy that answered when it named itself, and checked_at. Idempotent: a repeat keeps the same ownership value, so the TXT record stays valid
  • POST /emails/domains/:domain/redirect/verify: check DNS and visit the domain now; for a redirect Warmbly Cloud serves, Cloud checks and the answer is its verdict. Safe to repeat
  • DELETE /emails/domains/:domain/redirect: stop serving it, on Warmbly Cloud too when Cloud serves it. A repeat is a 404
  • PUT /emails/domains/:domain/vendor-forwarding: url; the vendor account holding the domain forwards its root there. An empty url removes the forwarding where can_unforward. Answers the updated vendor_domain. Idempotent
  • POST /emails/domains/:domain/vendor-tracking: host, a subdomain of the domain; the vendor writes its CNAME to this instance's tracking host, then every mailbox on the domain uses the host. Answers like PUT .../tracking. Safe to retry: the record is replaced, not added

  None of these takes an Idempotency-Key; the retry behavior of each is stated above. Changes to vendor connections, grants and redirects publish AUDIT_CREATED with entity_type mailbox_vendor, mailbox_grant or domain_redirect. Error codes are under mailbox source refusals

• POST /emails/onboarding/oauth/reauth/:id, PUT /emails/onboarding/smtp-imap/:id (reconnect an existing mailbox after a credential change; JWT permission MANAGE_EMAILS)

• POST /emails/onboarding/app-password/:id (JWT permission MANAGE_EMAILS): move a mailbox off per-mailbox Google sign-in onto Gmail's IMAP and SMTP with app_password, a 16-letter Google app password (spaces are ignored). The password is checked against Gmail's servers before anything is stored, with the same refusals as an SMTP/IMAP connect; on success the mailbox becomes smtp_imap in place, keeps its imported mail, campaigns and warmup, and answers 200 with the mailbox. 409 mailbox_not_google_signin for any other mailbox, including one already switched, so a repeat changes nothing and takes no Idempotency-Key; 400 app_password_invalid when the value is not 16 letters. Publishes AUDIT_CREATED with entity_type email_account

• GET /oauth/authorize/details, POST /oauth/authorize (the consent flow: a human approves a third-party app, and the grant carries only the scopes the member's role covers). POST /oauth/authorize requires a recent confirmation (POST /auth/reauth), like creating an API key

• GET /oauth/authorized-apps, DELETE /oauth/authorized-apps/:id (apps the user has authorized)

• GET /oauth/workspace-authorizations, DELETE /oauth/workspace-authorizations/:id/members/:userId (every member's authorized apps, and revoking one; JWT permission MANAGE_API_KEYS or MANAGE_SETTINGS). A revoke succeeds when there is nothing to revoke and publishes AUDIT_CREATED with entity_type oauth_authorization

• POST /getaway (websocket bootstrap)

• GET /realtime/info

• GET /me/danger-zone, POST /me/danger-zone/delete, DELETE /me/danger-zone/delete

• GET /me/views/:view, PUT /me/views/:view, DELETE /me/views/:view (the signed-in member's own column layout and sort for a dashboard list in the current workspace; view is contacts or campaign_leads, or unibox_rail for the unibox scope rail, which saves a layout of favorites, hidden, order and section_order instead of columns. Personal to the session, so no API scope reaches it)

• GET /invitations, POST /invitations/accept

• All of /organization/* (create, switch, members, invitations, transfer ownership, avatar, danger zone)

• GET /website-tracking/settings, PATCH /website-tracking/settings, POST /website-tracking/settings/rotate-key (the website tracking snippet's consent mode, location precision, allowed hosts and retention; JWT permission MANAGE_SETTINGS. The rotate is bodyless and safe to repeat, each call issues a new key)

• All of /subscription/* (checkout, portal, cancel, change-plan, preview-change, enterprise-inquiry, discounts, referrals, etc.)

• All of /auth/cli/* except the two handshake routes below (GET /auth/cli/codes/:code, POST /auth/cli/codes/:code/approve, POST /auth/cli/codes/:code/deny: the browser half of warmbly auth login, where a signed-in member reviews the code a CLI is showing and authorizes it. Approving mints an ordinary API key, so it requires the MANAGE_API_KEYS organization permission and a fresh authentication, is session-only (an API key must not be able to mint another one this way), and caps the key to the scopes the approver's role allows. GET /auth/cli/codes/:code?organization_id= adds granted_scopes and granted_scope_names: what approving into that workspace would grant)

• All of /pool-link/* and /cloud-link/* (the self-hosted warmup pool link: approving an instance's code, listing and unlinking instances, reading the pool plan's price and opening its checkout, and on a self-hosted instance the connect flow and mailbox enrollment). /cloud-link/* exists only on a self-hosted instance. The link belongs to the whole instance, so linking and unlinking it (/connect, /connect/poll, DELETE /cloud-link) and the linked cloud workspace's mailboxes (/workspace-mailboxes, .../adopt) take a platform admin holding manage_settings whose session presented a second factor (admin_mfa_required otherwise). Reading the link and putting a workspace's own mailboxes on it (GET /cloud-link, /mailboxes, enroll, pause, resume and the Google and Microsoft sign-in under /oauth/*) take the workspace's MANAGE_EMAILS. POST /pool-link/codes and POST /pool-link/poll are public and per-IP rate limited: they are the device-code handshake an instance uses before it has a token, and /pool-link/instance/* accepts only an instance token. /pool-link/instance/oauth/*, /pool-link/instance/mailboxes/:id/token, /pool-link/instance/workspace-mailboxes and /pool-link/instance/mailboxes/adopt are the cloud-managed mailbox surface (Google and Microsoft sign-in on Warmbly's OAuth apps, brokered access tokens); their instance-side counterparts are /cloud-link/oauth/* and /cloud-link/workspace-mailboxes/*. /pool-link/instance/redirects (list), and GET, PUT, DELETE and POST .../verify on /pool-link/instance/redirects/:domain, are the root redirects Warmbly Cloud serves for the calling instance; the instance drives them through PUT /emails/domains/:domain/redirect with served_by: "cloud", and GET /pool-link/instance carries redirects (available, host, limit, used)

• All of /admin/*. DELETE /admin/instance/invitations/expired requires platform admin manage_organizations and an MFA-verified session. It removes only expired invitation records across all workspaces, leaves active invitations and membership unchanged, records an admin audit entry, and returns { "cleaned": true }. The admin panel confirms before calling it.

POST /subscription/checkout, POST /subscription/portal, POST /subscription/cancel, POST /subscription/change-plan and GET /subscription/preview-change require the MANAGE_BILLING organization permission; reading the subscription, its limits, trial and features needs only membership. POST /subscription/portal requires an existing Stripe billing customer. A workspace without one receives 400 with code bad_request and a message to complete checkout first; free and operator-granted plans alone do not create a billing customer.

Referrals and discounts

The referral program and billing discount history are part of /subscription/*, so they are JWT only and never accept an API key. There is no API permission scope for them; browser callers are gated by the org permission below. The discount validation and checkout endpoints are listed under Subscription and billing in the reference.

AI credits

Credit balance, top-up purchases, and the transaction log are part of /subscription/*, so they are JWT only and never accept an API key. Purchases are fulfilled only in the Stripe webhook, never in the checkout call. See the AI credits guide for what each action costs and the pack and reset rules. GET /subscription/credits carries unlimited (boolean): true on a deployment with BILLING_PROVIDER=none, where the ledger is bypassed and every balance and allowance field is zero and meaningless.

AI assistant

Remie, the dashboard AI assistant, is JWT only: sessions are private to the member who started them. The message and approval runs stream over Server-Sent Events. Each tool Remie runs is gated by the member's own organization permission bits, so Remie can never do more than the member could by hand. See the Remie guide. (API-key and OAuth callers reach the same tools through the MCP server or the REST agent-tools surface, each tool gated by its own scope.)

POST /ai/sessions/:id/approve takes {"decision": "approve" | "deny" | "always_allow", "tool_call_id": "..."}. tool_call_id is required and must be the call the session is waiting on (the tool_call_id of its approval_required event, or pending.tool_call_id from GET /ai/sessions/:id/messages); any other answers 409 approval_not_pending, and so does a second decision on the same call. always_allow saves a workspace policy only for a member with manage_settings and only for a tool that may be always allowed; otherwise it approves this one call. The approval_required event and pending carry arguments (every argument as indented JSON with sorted keys, capped at 16 KiB, with arguments_truncated), preview for a send (from, to, subject, body, body_html), and always_allow_offered.

GET /ai/tool-policies lists the tools the assistant runs without asking (tool_name, created_by, created_by_name, created_at); DELETE /ai/tool-policies/:tool revokes one. Both audit as ai_tool_policy.

AI skills

Org playbooks the AI features follow (see the AI skills guide). Gated on manage_settings for JWT callers, or the AI_AGENT scope for API keys. Creating, editing or deleting one with an API key also needs the member who created the key to hold manage_settings.

Agent tools (REST)

The AI tool registry over plain HTTP for function-calling agents that do not speak MCP (see Agent tools). Like the MCP endpoint, it needs AI_AGENT (or use_ai for JWT callers); each tool then enforces its own permission, the list reflects only what the caller may use, and send-class tools are never exposed.

Connected MCP servers

External MCP servers whose tools the assistant can use (see Connect MCP tools). JWT-only and manage_settings-gated; bearer tokens are sealed with the org key and never returned.

Slack

The Slack panel's routes. They are session-only: linking binds a Slack account to the signed-in person, and an API key has no person to bind. Settings changes and link removals publish AUDIT_CREATED with entity_type integration.

The two /integrations/slack/link routes that take a code do not need a workspace selected, because the code names one. GET /integrations/slack/status reports app_configured (the instance has a Slack app) and interactive_configured (it also has the signing secret, so the assistant and buttons work), so a client can tell what is available before calling anything else. The settings and channel routes answer 404 slack_not_connected until the workspace connects Slack. Error codes are under 404 and 503.

MCP server

POST /v1/mcp exposes the tool registry over the Model Context Protocol streamable-HTTP transport. It accepts an API key or an OAuth 2.1 access token holding AI_AGENT (an unauthenticated request gets the RFC 9728 discovery challenge). Each tool is gated by its scope, tools/list reflects only what the credential allows, and send-class tools are never exposed. Per-key rate limits apply.

Public

• GET /health
• POST /auth/cli/code, POST /auth/cli/poll (the CLI device-code handshake, per-IP rate limited. Public by necessity: the CLI has no credential until the flow completes. POST /auth/cli/code returns device_code, user_code, verification_uri, verification_uri_complete, expires_in and interval; polling returns {"status":"pending"} until a member decides, then {"status":"approved"} carrying the minted key exactly once, or {"status":"denied"}. An unknown or expired device_code is a 404, so a poller cannot probe for live handshakes)
• POST /webhook/stripe (Stripe signature)
• POST /api/v1/integrations/hubspot/webhooks (HubSpot app webhooks, verified with the X-HubSpot-Signature-v3 signature over the app's client secret and refused when older than five minutes. A delivery only makes the next read of the named record come sooner; see HubSpot)
• POST /api/v1/integrations/pipedrive/webhooks/:connectionId (Pipedrive webhooks Warmbly registers for one connection when a workspace switches to Pipedrive. Authenticated by HTTP Basic auth with a password derived from the connection and the app's client secret. A delivery only makes the next read of the named record come sooner; a connection no workspace runs its CRM on answers 410. See Pipedrive)
• GET and POST /api/v1/integrations/pipedrive/app/panel, /app/enroll and /app/pause (the Warmbly JSON panel on Pipedrive person and deal pages and its two JSON modals). Pipedrive signs each call with a JWT over the app's client secret, passed as the token query value and pinned to HS256; the user and company it names must match the userId and companyId query values, and a repeated value is refused. The company selects the one workspace in Pipedrive mode with a live connection to it, and each call acts as the member matched to that Pipedrive user, with its permissions. See working from inside Pipedrive
• POST /api/v1/integrations/hubspot/app/card, /app/enroll, /app/pause (the Warmbly card on HubSpot contact records) and POST /api/v1/integrations/hubspot/actions/enroll, /actions/campaigns (the "Add to Warmbly campaign" workflow action). HubSpot signs each request with the app's client secret (X-HubSpot-Signature-v3, over the public backend URL). The card routes take the portal and HubSpot user from the query values HubSpot appends, exactly one of each, and act as that user's matched member with its permissions; the webhook and workflow action routes refuse a request carrying those values. The portal selects the one workspace in HubSpot mode with a live connection to it. See working from inside HubSpot
• POST /webhook/campaign, /webhook/email, /webhook/user-email (Google OIDC token from Cloud Tasks)
• GET /addresses/google/callback, GET /addresses/outlook/callback (OAuth bouncer pages)
• POST /oauth/token, POST /oauth/revoke (OAuth token endpoints, authenticated by the client's id and secret, or PKCE for public clients)
• POST /oauth/register (OAuth dynamic client registration, RFC 7591; open and per-IP rate-limited)
• GET /.well-known/oauth-authorization-server, GET /.well-known/oauth-protected-resource (OAuth discovery metadata)

On the backend's host but outside /v1, called by Slack and never by an API key or a session:

• POST /api/v1/integrations/slack/events, POST /api/v1/integrations/slack/interactivity (Slack signature). Each request must carry a valid Slack X-Slack-Signature made with the instance's signing secret over a timestamp within five minutes, and its body is capped at 1 MiB. A bad signature is 401 unauthorized, and nothing in the body is parsed before the signature checks out. With no SLACK_SIGNING_SECRET set they answer 503 slack_not_configured. They answer Slack within its three-second limit and do the work afterwards. See Slack app

On the tracking service (the TRACKING_DOMAIN host, not the API), also public and rate-limited per source:

• GET /t/o/:task_id.png (open pixel), GET /c/:link_id (click redirect)
• GET /tracking.js (the website tracking snippet), POST /p (page-view ingest; JSON body up to 8 KB, 429 over budget, 204 otherwise. Nothing in the request can name a contact)
• A visit to a sending domain's root (or its www) that a workspace pointed here. On a verified domain every path except /health answers 302 to its website with Cache-Control: public, max-age=300, before any route above; an unknown host is a 404. The forms service answers a verified redirect domain the same way

Notes

• When a route has both a JWT permission and an API permission listed, the dual-auth middleware checks the JWT user's organization role for browser callers and the key's permission bitmask for API key callers. They're independent gates: a user's role doesn't constrain what an API key can do beyond what was granted at creation.
• Every API key request is logged to api_key_usage_logs with the endpoint pattern (e.g. /campaigns/:id), method, IP, user-agent, response status, and elapsed milliseconds. JWT requests are not logged here.
• Rate limit categories (X-RateLimit-* headers) are scoped to the underlying user, not the key; every key issued by a user shares the user's quota.

See also

• Authentication
• Permissions Reference
• Error Codes