API keys and scopes
Your tests call the API with an API key. A key belongs to one workspace: every inbox, message and pattern it
reaches is that workspace’s, and the flat /v1 routes need no workspace in the path. Send it as a bearer token:
Authorization: Bearer wx_...Creating and revoking keys
Section titled “Creating and revoking keys”Keys are created and revoked on the workspace’s API keys page in the dashboard, by a
workspace Admin. A key starts with wx_ and is shown once, when it is created: Waridex stores only a hash of it, so
copy it into your CI secrets straight away. A revoked key is refused from its next request with
401 auth.unauthorized. A workspace holds at most 20 active keys.
Scopes
Section titled “Scopes”A key holds exactly the scopes listed on it, at least one; no scope includes another. A new key starts with the three
a test run needs: email:read, inbox:create and inbox:delete.
| Scope | Allows |
|---|---|
email:read | list inboxes and tags; list, search, read and download messages; wait; read patterns, the workspace and its statistics |
email:delete | delete messages |
email:inject | inject a message into an inbox of the workspace |
inbox:create | create inboxes |
inbox:delete | delete inboxes, and delete every inbox of a tag |
pattern:manage | add and delete pinned patterns |
authenticator:use | the whole authenticator channel: add, list, read and delete authenticators, purge them by tag, and read their codes and the code log |
Two more scopes exist for people rather than keys and can never be put on one: keys:manage, which manages the
workspace’s API keys, and workspace:admin, which renames the workspace and covers everything else under it. A
workspace Admin holds both.
A few scopes can also be put on a key reserved for features that are not available yet — email:reply,
webhooks:manage and the sms: scopes — so a key made now needs no change when those features arrive. They allow
nothing today, and the dashboard marks them as reserved.
A call without the scope it needs is refused with 403 scope.missing, and the problem’s
requiredScope names the scope. People signed in to the dashboard are held to the same scopes through their
workspace role.
Rate limits
Section titled “Rate limits”Each key may make 60 wait calls and 600 other calls a minute. Adding an
authenticator and asking it for a code count against the wait allowance, not the
other one, since they too may hold. Beyond either, the API answers
429 rate_limit.exceeded with a Retry-After header giving the seconds to wait.
Test suites that run many workers in parallel can give each pipeline its own key.