Scopes
Scopes limit what an access token can do in Bill.DO. Choose them when you create an access token. Start with the narrowest scope that covers your integration. The shared scopes guide explains how parent scopes and write access work.
Each endpoint in the REST API reference lists its required scope under security. The same scopes apply to the tools of the MCP server.
Available scopes
Broad scopes
| Scope | Access |
|---|---|
billdo | Every user-facing Bill.DO API operation |
billdo:read | Every resource read operation |
billdo:write | Every resource write and read operation |
Getting the team, its plan limits, and its connected accounts works with any Bill.DO read scope.
Accounts
| Scope | Access |
|---|---|
billdo:accounts:read | List and retrieve the connected DigitalOcean accounts, their projects and resources, current and predicted usage, and usage history |
Bill.DO only reads from DigitalOcean, so accounts have no write scope. Connecting and disconnecting accounts happens in the Bill.DO dashboard.
Invoices
| Scope | Access |
|---|---|
billdo:invoices:read | List the DigitalOcean invoices of the connected accounts and download their PDFs |
Invoices are not selected by default
New tokens only get billdo:invoices:read when you select it, because invoices are financial documents. The broad scopes billdo and billdo:read include it too.
Alerts
| Scope | Access |
|---|---|
billdo:alerts:read | List and retrieve billing alerts and their current values |
billdo:alerts:write | Create, update, and delete billing alerts; also grants alert reads |
Scopes are hierarchical. A resource write scope includes the matching read scope. billdo:read grants every resource read scope, billdo:write grants every resource write and read scope, and billdo grants everything. A resource scope does not grant access to unrelated resources.
Example token configurations
Report spend
Code
The token can read the usage, usage history, projects, and resources of every connected account. It cannot see invoices or alerts.
Manage alerts from automation
Code
The token can list the accounts and create, change, and delete their alerts. It cannot read the usage history or resources.
Collect invoices for bookkeeping
Code
The token can list the accounts and their invoices and download the PDFs. Store this token like the invoices it can read.