Authentication & errors

The Public API authenticates every request with an API key passed as a bearer token:

Authorization: Bearer <key>

A missing or invalid key is rejected before any handler runs — see the Api.* codes under Errors below.

Key types

Workspace rules

Every endpoint path includes a :workspaceId. The key must be authorized for that workspace:

• Workspace key (ti_ws_) — the path :workspaceId must match the workspace the key was created for. Using it against any other workspace returns Api.WorkspaceForbidden (403).
• Personal key (ti_pk_) — you must be a member of the target workspace. Your effective role is your live membership role in that workspace; if your membership changes or is removed, access changes immediately. A non-member workspace returns Api.WorkspaceForbidden (403).

Soft-deleted workspaces are always rejected.

Scopes

Each key carries a set of scopes. A request must hold the scope its endpoint requires; otherwise it returns Api.ScopeForbidden (403). A scope is also capped by the key's role in the workspace — a write scope held by a VIEWER is still denied.

Most read scopes are capped at VIEWER and most *:manage scopes at EDITOR. Two are capped higher, and the table below says so on each: workspace:manage and billing:read both require ADMIN.

Grant a key only the scopes it needs. Read-only integrations should never hold a *:write or *:manage scope.

Revocation

Keys can be revoked from Settings → API keys in the web app. Revocation is immediate — the next request made with a revoked key returns Api.InvalidKey (401). There is no grace period.

Rate limits

The Public API applies two independent limits to every request. A request must pass both to be served.

Layer 1 is what your plan buys. Layer 2 is a fixed infrastructure ceiling — it is the same for every customer and no plan raises it.

Both use a fixed 60-second window that resets on the wall clock minute, not 60 seconds after your first call.

Buckets

The per-key layer counts requests into three separate buckets:

Each bucket has its own counter, so heavy reads do not consume your write budget.

Bulk endpoints are counted separately rather than just more cheaply: a single bulk call can act on as many as 50 accounts, so it is not one unit of work. A bulk route is charged to bulk regardless of its HTTP verb — POST …/accounts/bulk/tags and the read-shaped POST …/accounts/bulk-status both draw on bulk, not on write or read.

Plan tiers

Per-key budgets, in requests per minute:

Billing cycle does not affect these numbers — monthly, quarterly, and yearly plans on the same tier share one budget.

The full-access trial is deliberately more generous than Starter so the API can be evaluated properly during it. If a workspace has no resolvable plan, the Free budget applies.

The IP ceiling

Every request also counts against 100 requests/minute per IP address, across all three buckets and all API keys.

Because the ceiling is higher than the largest per-key budget, a single key can never reach it on its own. It binds only when several keys call from the same address — so two things are worth knowing:

• Multiple API keys behind one server, or many workspaces automated from one machine, draw on one shared 100/min budget.
• If you integrate through a hosted platform (Zapier, Make, n8n) or from behind a corporate or cloud NAT gateway, you may share an outbound IP with other TrulyInbox customers and therefore share this ceiling. If you expect sustained volume, call from an address you control.

Response headers

Every response — including a rejected one — carries the state of both layers:

The unprefixed X-RateLimit-* headers always describe the per-key layer, so they stay comparable to your plan. Watch X-RateLimit-IP-Remaining separately if you call from a shared address.

Use X-RateLimit-Remaining to pace your client and back off as it approaches zero. Read the limits from GET /v2/workspaces/{workspaceId}/rate-limit rather than hard-coding them — that endpoint reports the budget actually being enforced for your key, alongside current consumption.

Exceeding a limit

Either layer rejects with HTTP 429 and the standard envelope, carrying Api.RateLimitExceeded in errorCode:

{
  "success": false,
  "data": null,
  "errorCode": "150005",
  "errorMessage": "Read endpoint limit reached. Resets in 34 seconds."
}

errorMessage names which limit you hit — the bucket (Read / Write / Bulk) for the per-key layer, or explicitly the IP address for the ceiling. When a request breaches both, the plan message is returned, since that is the one you can act on.

The X-RateLimit-* headers are present on the 429 as well, and Retry-After gives the seconds until the window rolls. Honour it rather than retrying immediately; it is never less than 1.

Note that a rejected request still consumes budget in both layers, so retrying inside the same window makes matters worse — wait for the reset.

Failed authentication

Separately from the above, repeated failed API-key attempts from one IP are locked out: 5 failures trigger a 15-minute cooldown, returning 429 with Api.TooManyFailedAttempts and a Retry-After. A missing key does not count as a failure; an invalid or revoked one does.

Errors

The response envelope

Every Public API response — success or failure — uses the same envelope:

{
  "success": true,
  "data": { },
  "errorCode": null,
  "errorMessage": null
}

The per-endpoint reference documents the shape of data for each operation. The envelope wrapping it is documented here, once — it is identical for every endpoint.

Error codes

Errors carry a stable, 6-digit errorCode. Branch on errorCode, never on errorMessage — messages are for humans and may change; codes are the contract.

The first two digits identify the feature namespace. Public-API authentication, authorization, and rate-limiting errors live in the Api (feature 15) namespace. Every /v2 request passes through the guard stack (ApiKeyGuard → ScopesGuard → WorkspaceRoleGuard → RateLimitGuard), so these are the codes you will see most:

Endpoints may also return feature-specific error codes from the domain they touch (for example, an unknown account id). Those codes follow the same 6-digit shape and the same envelope; handle them by code.

Key-management codes

Creating, listing, and revoking keys happens on the internal (session-authenticated) /api-keys endpoints — the same surface the web app's API-keys settings screen uses. Those operations return their own codes within the Api (15) namespace:

Example error response

{
  "success": false,
  "data": null,
  "errorCode": "150003",
  "errorMessage": "Your API key doesn't have the required scope for this action."
}