Scope what an agent is allowed to do

API keys carry one of four profiles: Read only, Read and draft, Billing, or Full. The server checks the profile on every call and re-checks expiry and revocation when the tool runs, so an agent can never exceed the key it was given.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: Anyone handing an agent a key, especially before letting it send documents or record payments.
Billr capabilities used: list_invoicescreate_invoicesend_invoicerecord_paymentdelete_time_entry

What you need first

Access to Agents → API Keys in the dashboard.
A decision about what the agent should be able to do without asking: read, draft, send, or take payments.
A shell or secret manager to hold the key, so it never lands in a repository file.

Step by step

01Pick the smallest profile that works
Read only can list and fetch. Read and draft adds creating and editing drafts, including time and expenses. Billing adds send_invoice, send_estimate and record_payment. Full adds delete_time_entry and delete_expense.
02Understand what each tool needs
Every tool declares one scope: read, write, send, payments or delete. The tool reference lists all 53 tools with the scope beside each name, so you can check a workflow before granting it.
03Connect the key, never commit it
Pass the key as a bearer token in your client configuration, or reference it through an environment variable. Keys expire after 90 days; the same screen revokes one immediately.
Example
```
# Claude Code, local scope by default
claude mcp add --transport http billr https://mcp.billr.cc \
  --header "Authorization: Bearer billr_sk_your_key"
```
04Read the audit trail
Each tool call is recorded against the key that made it, with a status of succeeded or failed. Agents → Audit is the fastest way to see what a session actually did.

Worked example

Fictional account, field names as returned by the server

You say

With a read-only key, list the invoices that are still unpaid.

Your agent calls

list_invoices { "status": "unpaid" }

Expected response, abridged. The same key is refused on any write, send, payment or delete tool.

{
  "summary": "3 invoices found.",
  "invoices": [
    {
      "invoice_number": "INV-1146",
      "status": "sent",
      "currency": "USD",
      "balance_due": 1512.5,
      "is_overdue": false
    }
  ]
}

Limits and gotchas

Profiles are fixed sets, not per-tool checkboxes. If a workflow needs one send and nothing else, the key needs the billing profile.
Task pricing and task invoice approval are human steps regardless of the key profile; list_billing_policies says plainly that agents cannot approve pricing.
Scope is re-checked when a tool executes, so revoking a key takes effect on the next call rather than at the next restart.
A key scoped to several businesses still needs business_id on writes.
Nothing about a key limits what the model says in chat; it limits what the server will accept.

Troubleshooting

A tool answers "API key is expired, revoked or lacks permission for this tool.": Either the key is expired or revoked, or its profile does not include that scope. Check the key in Agents → API Keys and create a new one with the profile the workflow needs.
The agent cannot send even though it can draft: Sending needs the billing profile. Create a billing key for that workflow, or send from the dashboard where a person is already in the loop.
A key leaked into a repository or a screenshot: Revoke it in Agents → API Keys; revocation survives until the key expires. Create a replacement and store it in an environment variable, not in a committed file.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.