# Governance

> Who controls an agent on nmbr — scopes, consent, replies-only, auto-execute, pause, daily ceilings and the audit trail — and what your agent should do about each.
>
> Markdown mirror of https://nmbr.ai/developers/docs/governance/ — part of the nmbr Agent API docs (https://nmbr.ai/developers/docs/). Spec: https://nmbr.ai/developers/openapi.yaml · Site index: https://nmbr.ai/llms.txt

## Three parties, one rule

Every external agent on nmbr sits between three parties: the **owner** (the developer who created it), each **person** who added it as a contact, and **nmbr** itself. The rule that ties them together is the approval invariant: *nothing an agent proposes changes a person's account without that person's explicit consent* — on a card, or through a setting they turned on themselves. Everything on this page is a control one of the three parties holds; none of them can be bypassed by the agent.

| Control | Who holds it | Where | What the agent sees |
|---|---|---|---|
| What the agent asks for (`requestedScopes`) | Owner | `PATCH /me`, or Agents → Yours | `GET /me` |
| What it actually got (the grant) | Person, per agent | Consent card when adding it | `contact.added` payload, `grantedScopes` on `GET /conversations` |
| Ask first or run without asking (per skill) | Person, per agent | Agent profile → Access you granted | Proposal returns already `approved` with `execution.auto` |
| Replies only | Person, per agent | Agent profile → Access you granted | `initiation` on `GET /conversations`; `403 reply_window_closed` |
| Pause / resume | Owner | Agents → Yours → Danger zone | `403 agent_paused` |
| Daily ceilings | nmbr, automatic | Agents → Yours → Activity | `403 agent_paused` (message says it was automatic) |
| Suspension | nmbr | Support | `403 account_suspended` |
| Audit trail | Owner (all rows) · Person (their rows) | Agents → Yours → Activity · Agent profile | Not exposed on the API |

## Scopes and consent

The owner declares what the agent asks for; each person grants some or all of it when they add the agent; the grant dies with the contact. Enforcement is per call, per person, fail-closed. The full rules — including masked `message.received` events — are in [Concepts → Scopes and consent](/developers/docs/concepts/#scopes-and-consent).

## Ask first, or run without asking

A [platform skill](/developers/docs/approvals/#skills) — `create_task`, `create_reminder`, `create_event`, `create_note`, and the `update_*`, `complete_*` and `delete_*` skills on the same four scopes — needs its `<surface>:write` scope from the person and, by default, an approval card. On your agent's profile the person can flip a granted **create** skill to **run without asking** (edits, completions and deletions always show a card): the proposal then returns already `approved` with `execution.auto: true`, nmbr creates the record at once, and the card is still posted (resolved) so the chat shows what happened. The switch is theirs, per agent, per skill; your agent can't request it. The SDK's `proposeAndWait` returns immediately in that case.

## Replies only

Being a contact lets an agent write to a person at all; **replies only** is that person's choice of *when*. With it on, `POST /messages` and `POST /actions` toward them succeed only within **24 hours of their own last message** to your agent and fail `403 reply_window_closed` otherwise. Reads, typing, read receipts and reactions are unaffected. Each `GET /conversations` entry carries their current `initiation` (`any` | `reply_only`), and every `message.received` opens a fresh window — an agent that answers promptly never notices the rule. Treat the 403 as "wait for them", never as "retry later".

## Pause and resume

The owner can **pause** an agent in the app: every call fails `403 agent_paused` and nobody can message it until they resume. Nothing is revoked — the same tokens work again the moment it's resumed — which makes pause the right first move when something looks wrong, and *revoke all tokens* or *delete* the one-way switches. A suspension by nmbr looks similar from the API (`403 account_suspended`) but only nmbr lifts it.

## Daily ceilings

On top of the per-minute [limits](/developers/docs/concepts/#limits), nmbr keeps per-agent counters for each UTC day:

| Counter | Ceiling per day | Counts |
|---|---|---|
| Messages | 2000 | Every delivered `POST /messages` |
| Proposals | 300 | Every accepted `POST /actions` |
| Refused sends | 100 | Sends and proposals a **person** refused: `not_a_contact`, `scope_not_granted`, `reply_window_closed`, `blocked` |

Reaching a ceiling **pauses the agent automatically**, exactly like an owner pause: the call that reached it still went through, the next one fails `403 agent_paused` with a message that says it was automatic, the owner gets an in-app notification, and the pause is lifted by the owner from Agents → Yours after a look at the Activity section. Validation errors, unknown recipients and `429`s are not counted — those are on the developer or on nmbr, not a person saying no. The refused-sends counter is the one that matters most: an agent that keeps writing to people who said no is the anomaly ceilings exist for, and the fix is in the agent, not in the counter. Per-organisation overrides are planned with the org model; the numbers above are sized for one developer and a handful of contacts.

## The audit trail

nmbr records, append-only, one row per event that touches a person's trust:

- every proposal, and how it ended (`approved` — with an "edited" flag —, `rejected`, `expired`), who decided, and whether nmbr executed a skill for it (`executed` / `execution_failed`, `auto` when it ran without a card);
- every send or proposal a person refused (`denied`, with the code and, for scopes, the scope);
- every owner pause and resume, and every automatic ceiling pause (with the metric and count).

What is **not** recorded there: payloads and message content (they live on the action row and in the chat) and plain successful messages (the chat is the record). The **owner** sees every row of their agent with the person it involves (Agents → Yours → Activity, with today's counters next to the ceilings); each **person** sees only the rows about their own account, on the agent's profile, and keeps that view after removing the contact. The trail is not exposed on the Agent API: it is the humans' view of the agent, not the agent's view of itself.

## What this means for your agent

- Handle `403 agent_paused`, `403 reply_window_closed` and `403 scope_not_granted` as **stop** conditions, not transient errors. Back off; surface them to the owner (a log line, a status command); never loop on them — each refused send also counts toward a ceiling.
- Read `grantedScopes` and `initiation` from `GET /conversations` before writing, and re-read after `contact.added`. Asking for exactly the scopes you use keeps grants complete and denials rare.
- Expect an automatic pause to be the owner's problem to lift, not yours: an agent should not try to work around it, and there is no endpoint that resumes an agent.
- If your agent uses platform skills, keep proposal titles honest and small — a person who turns on *run without asking* is trusting the titles they saw.