Scopes
Every API key scope and the endpoints each one unlocks
When you create an API key you pick one or more scopes. A key with no scopes is rejected at creation. Each request is then checked against the key's scopes — a missing scope returns 403.
Available scopes
| Scope | Actions |
|---|---|
emailInbox | read, delete |
tests | read, create, update, delete, run, cancel |
testRuns | read |
schedules | read, run, pause, resume |
emailInbox
| Action | What it unlocks |
|---|---|
emailInbox:read | GET /v1/email-inboxes, GET /v1/email-inboxes/limits, GET /v1/email-inboxes/:inboxId/messages, GET /v1/email-inboxes/:inboxId/messages/:messageId |
emailInbox:delete | DELETE /v1/email-inboxes/:inboxId |
tests
| Action | What it unlocks |
|---|---|
tests:read | GET /v1/tests, GET /v1/tests/:testId, GET /v1/tests/:testId/steps, GET /v1/tests/:testId/steps/:stepId, GET /v1/tests/:testId/files, GET /v1/tests/:testId/revisions, GET /v1/tests/:testId/revisions/:revisionId, POST /v1/tests/export |
tests:create | POST /v1/tests, POST /v1/tests/:testId/duplicate, POST /v1/tests/import |
tests:update | PUT /v1/tests/:testId, POST /v1/tests/bulk-update-status, POST /v1/tests/bulk-update-tags, POST /v1/tests/:testId/revisions |
tests:delete | DELETE /v1/tests/:testId, POST /v1/tests/bulk-delete |
tests:run | POST /v1/tests/remote-run (by testIds or tagId), POST /v1/tests/:testId/remote-run |
tests:cancel | POST /v1/test-runs/:runId/cancel |
testRuns
| Action | What it unlocks |
|---|---|
testRuns:read | GET /v1/test-runs, GET /v1/test-runs/latest, GET /v1/test-runs/stats, GET /v1/test-runs/:runId, GET /v1/test-runs/:runId/tests, GET /v1/test-runs/:runId/artifacts, GET /v1/test-runs/:runId/report |
schedules
| Action | What it unlocks |
|---|---|
schedules:read | GET /v1/schedules, GET /v1/schedules/:scheduleId |
schedules:run | POST /v1/schedules/:scheduleId/trigger |
schedules:pause | POST /v1/schedules/:scheduleId/disable |
schedules:resume | POST /v1/schedules/:scheduleId/enable |
Creating, editing and deleting schedules stays session-only.
Chain rules
Every /v1/tests route requires tests:read in addition to any write scope. For example, POST /v1/tests requires both tests:read and tests:create — the key must have both actions granted for the tests scope.
Similarly, every /v1/steps route requires tests:read (see below), every /v1/test-runs route requires testRuns:read, and every /v1/schedules route requires schedules:read.
Cancelling a run (POST /v1/test-runs/:runId/cancel) requires both testRuns:read and tests:cancel.
Steps and shared steps
There is no separate steps or sharedSteps scope on API keys. Step and shared-step endpoints are authorized through the tests scope:
- Reading steps and shared steps (
GET /v1/steps/...,GET /v1/tests/:testId/steps,GET /v1/tests/:testId/files) requirestests:read. - Writing steps and shared steps (
PUT /v1/steps/:stepId/...) requirestests:update.
This is intentional: a test's steps, shared steps, file attachments, and saved revisions are all part of the test's definition. Granting tests:read therefore also grants read access to that test's steps, shared step definitions, step file attachments, and revisions.
Resources not reachable with an API key
The following resources require an active console session and cannot be accessed with an API key:
- Projects, branches, secrets, tags, config presets
- Creating, editing or deleting schedules
- Billing and audit log
- Webhook management
- API key management itself
- Creating email inboxes (
POST /v1/email-inboxes)