Token Scopes (Organization vs Customer)
API tokens can optionally be created with a Customer Scope:
- Organization-wide token: can read/modify resources across all customers of the organization.
- Customer-scoped token: can only read/modify resources (websites, maintenance windows, etc.) within that specific customer.
Customer-scoped tokens are recommended for agencies and external integrations. Requests outside the scope return 403 Forbidden.
A customer-scoped token never reaches organization-wide paths, regardless of HTTP method: organization settings and billing (/api/organizations/**, /api/organization/** except GET /api/organization), users, admin and platform-admin routes, escalation configuration, custom pricing and custom fields, Incident Management, creating or deleting customers. Such calls answer 403 with data.code: customerScopedTokenForbidden. Reading /api/organization and /api/package-configs stays possible. No API token can create another token.
Roles and the customer scope
Every request carries two things: a role (what kind of writes the actor may make) and a customer scope (which customers the actor sees). The scope is decided by the token's customer binding, or, for a user session, by the customer assignments of that user. Both must allow a call.
| Role | Who | Scope |
|---|---|---|
admin | Organization administrator | Organization-wide, always. |
editor | Organization team member | Organization-wide unless the user is assigned to specific customers; then confined to those. |
readonly | Customer self-service user | Always confined to the customers the user is assigned to. |
readonly is the self-service role a customer works with. Inside its own customer scope it may read and write: monitors, maintenance windows for its customer, notification channels of its customer, and so on. What it can never do is touch organization-wide resources: org-wide (tag-only) maintenance windows, organization settings and billing, users, creating customers. editor and admin are the organization roles; an editor that is assigned to customers is treated exactly like a customer-bound actor on those organization-wide resources.
Concretely, an actor with a restricted scope (a customer-scoped token, a readonly user, an editor with customer assignments) gets 403 with data.code: customerScopedTokenForbidden on:
- creating a customer (
POST /api/customers) - editing or deleting an org-wide maintenance window (
PATCH/DELETE /api/maintenance-windows/:idon a window without a customer) - organization settings, billing, users and the other paths listed above
and a tag-only maintenance window it creates is anchored to its single customer instead of becoming org-wide (see Create Maintenance Window).
A resource outside your scope is a 404
403 is reserved for what you may do: a role that may not write, a customer-scoped token on an organization path, a managed monitor. A specific resource that exists but belongs to another customer or another organization is, for you, indistinguishable from one that does not exist: the API answers 404 with the same data.code as for a missing id (websiteNotFound, monitorNotFound, customerNotFound, statusPageNotFound, …). Do not treat a 404 as proof that an id is free, and do not expect a 403 to tell you that something exists.
Note: Session-based authentication (cookies) is used for the web interface but is not recommended for integrations.