Authentication
Every call to api.sb carries a credential from Identity that names the Worker calling, the namespace it reaches and the environment it runs in.
Every call to api.sb carries a credential issued by Identity. It names the Worker calling, the namespace the call reaches, and whether it runs in test or live.
Who signs in, and how
Each caller signs in the way that suits where it runs, and every path ends in a credential from the same issuer.
| Caller | Signs in by | Holds |
|---|---|---|
| A Human at a terminal | npx startup-builder login, in the browser | A secret key stored for this machine |
| A Human in an MCP client | OAuth on first connect to https: | An access token with the scope they approved |
| An Agent seated in a Role | Its own identity | A Role session key for that seat |
| Server code and unattended Agents | A key created for them | A secret key |
| CI and deploy pipelines | Exchanging the runner's OIDC token | A 15-minute token, with no stored secret |
| A Startup's own Site and App | A key embedded in the page | A publishable key |
Keys covers each kind, its lifetime and how to rotate it.
Send the credential
Send it as a bearer token:
curl https:The SDK, the CLI and the MCP server read the same variable, STARTUP_BUILDER_API_KEY, before any stored sign-in. Set it once and every Interface uses it. npx startup-builder whoami --output json prints the Worker, scope and environment the next call uses.
Every call is attributed
Each Action records its credential's Worker as by and the Party it serves as for. Nothing runs anonymously.
shipnotes.dev is a Startup that writes changelogs from commits, and each of its Agents holds its own credential. When its support Agent refunds an Order, the record names that Agent, not the founder who seated it. Revoking its key stops it and no other Agent.
An Agent sending as a human, under delegation, carries that human's Mandate. The Action records the Agent as by, the human as for, and the Mandate it acted under.
Four checks, in order
A credential gets a call through the door. Four checks then decide what the call may do:
| Check | Asks | On failure |
|---|---|---|
| Scope | Does the credential reach this namespace and Verb? | 403 forbidden; no Action |
| Permissions | May this Worker run this Verb? | 403 forbidden; no Action |
| Mandate | Does the Agent's authority cover this Party and input? | The Action is born refused |
| Limits | Is the amount within bounds? | The Action waits on an Approval |
The first two fail at the door, so nothing is recorded. The last two are decisions about the business, so they land on the record. A missing, expired or revoked credential fails before all four, with 401 unauthorized.
Signing in from an MCP client
An MCP client discovers api.sb's authorization server on first connect and registers itself. Identity opens a browser sign-in, and the human picks the namespace and scope before approving.
The token the client receives names both the human and the client's Agent. Every Action it starts records the Agent as by and the human as for. To withdraw the grant, the human revokes it from their account, and the next call returns 401.
Next
- Keys: kinds of key, scopes, rotation and leaks.
- Environments: what
testandlivekeys reach. - Throttling: how fast one credential may call.