Authentication and scopes
REST requires a manual automation bearer grant, not an interactive session, legacy API token or MCP OAuth access token.
Authorization: Bearer <manual-automation-token>Issue and retire a grant
Section titled “Issue and retire a grant”- As an Admin, select the account and open Settings > MCP.
- Name the manual grant for its integration or environment.
- Select the minimum required scopes and an expiry within 90 days.
- Create it and copy the token shown once to private configuration.
- Verify capabilities or another authorized read.
Manual grants default to 90-day expiry. Rotation issues a replacement token, invalidates the old one and renews expiry to 90 days. Revocation disables the grant. OAuth connections are disconnected, not manually rotated.
Tokens bind to both the issuing user and account. Effective permission is the intersection of selected scopes, current membership/role and grant validity. A role change or loss of membership can remove access immediately.
Scopes
Section titled “Scopes”| Scope | Allows | Current role capability |
|---|---|---|
account:read |
Capabilities and billing guidance | View monitoring |
checks:read |
List/read safe check configuration | View monitoring |
checks:history |
History, runs, metrics and uptime | View monitoring |
incidents:read |
Safe incident timing reads | View monitoring |
notification_groups:read |
List safe group summaries | View monitoring |
dashboards:read |
List/read dashboards and existing public URLs | View monitoring |
checks:create |
Create supported checks | Manage checks |
checks:update |
Update supported check fields | Manage checks |
checks:ping_urls |
Retrieve secret heartbeat URLs | Read operational credentials |
notification_groups:assign |
Assign existing groups during check writes | Manage alerts |
dashboards:create |
Create private custom dashboards | Manage dashboards |
dashboards:update |
Update private custom dashboards | Manage dashboards |
dashboards:assign |
Attach/detach/reorder checks | Manage dashboards |
Read monitoring is available to all customer roles. Operational credential and write capabilities are available to Editor/Admin; see roles. Only Admin can manage these connections in settings.
Supplying an association field requires its assignment scope even when
you already have permission to create/update the check. Avoid selecting
checks:ping_urls for clients that only need health summaries.
Use HTTPS. A token in a query string is not supported authentication and is liable to leak in URLs and logs.