Flows

Two mechanisms carry most of the misunderstandings about this API: how a token appears without anyone pasting one, and why a write is two calls instead of one. Both are drawn here.

The diagrams are inline SVG — no runtime, and they follow the site's theme.

An AI client obtains a token

Nobody types a token into Claude or Cursor. The client discovers where to ask, registers itself, and the person consents in a browser. What comes back is scoped to one project and to the capabilities that were ticked.

Steps 3 and 4 are why nothing has to be configured by hand: the resource says where its authorization server is (RFC 9728), and the client registers itself rather than being pre-provisioned. Step 5 is the only human moment.

What the token is not: an account-wide key. It carries one project, and the capabilities consented to — see credentials for the three credential kinds and glossary for why a key that authenticates opens nothing on its own.

A change is proposed, then applied

There is no single-call write. A propose capability computes a diff and hands it back; applying it is a second, explicit call — and that call recomputes the diff before writing anything.

diff_stale is the most common refusal on this path, and it is a safety net, not a fault: someone — a person, or another agent — changed the target between the proposal and the apply, and applying now would silently discard their change. Recompute, review, apply again.

Two other refusals live here: diff_forbidden (409) when the proposal targets something it may not change, and diff_unsafe_content (422) when the outgoing content itself is refused. All three are in the error reference.