Keys for your code, OAuth for assistants

An owner or admin creates a key in the console, after a recent sign-in. It is shown once: bmk_live_… or bmk_test_…. We store a keyed hash of it, never the key, so we cannot show it to you again. Lose it and you revoke it and make another.

A key carries its scopes, an optional address allow-list, an optional expiry and its own rate limit. A test key exists only for a sandbox workspace and a live key never for one. Every call made with it is audited with the key as the actor.

Authorization: Bearer bmk_test_…

A route needs the scope named on its reference entry. A few routes also need a second scope, and their summary says so. A write scope also reads what it writes. A credential that holds a scope outside its type’s ceiling is refused, whatever its document says.

Assistants connect with OAuth against https://api.billingmart.com/mcp. Discovery is standard (RFC 9728 and RFC 8414), clients can register themselves (RFC 7591) or present a client metadata document, and PKCE with S256 is required.

The consent screen lists what the app asked for, grouped and in plain words, with the business picker and a choice between Ask (it may request actions) and Plan (it may only read and show what it would do). Reading contact details is off unless the person ticks it.

Every call through a grant re-reads the person who consented. Removed from the workspace: refused. Moved to viewer: the same token now reads only. Write scopes need a recent sign-in at consent, and a second factor where the workspace requires one.

The person, or an owner or admin, can narrow a grant or revoke it from Connected apps in the console. The next call sees the change; nobody has to reconnect. No tool can change its own grant.