Identity and access
How api.sb knows who is calling and what the call may do, before it runs.
Every call to api.sb answers three questions before it runs: who is acting, for whom, and by what right. The answers stay on the Action forever.
Who is acting
Three kinds of caller reach a Startup. People sign in once, with a passkey, an email link, or their own single sign-on. Agents carry their own credentials and never borrow a person's; programs hold a key.
A key starts with sk_test_ or sk_live_, and the prefix picks the environment. A key acts only in its own namespace and within its scopes. A key can mint a narrower key for a script or an Agent; no key can mint a wider one.
curl https:A missing or expired key returns unauthorized. A valid key without the right returns forbidden, and the error names the grant the caller lacks.
For whom
An Agent often acts for someone else: a founder, a Customer, or the Startup itself. It does so under a Mandate, a standing authorization to perform one Verb within a Limit until the Mandate expires. Authorize grants one; revoke ends it at once.
Let the support agent refund invoices up to $100 without asking me.Every Action records two names: the Worker that acted and the Party it acted for. An auditor reading a refund sees which Agent issued it and on whose authority.
By what right
A right always names a Verb on a Noun, within a scope, and may carry a Limit. Three grants supply it, and their origin matters.
| Grant | Comes from | Example at a churn-report Startup |
|---|---|---|
| Permission | A Role | The analyst Role may create and deliver reports. |
| Entitlement | An accepted Offer | A Customer on the weekly plan may read reports in its own Tenant. |
| Mandate | A Party's authorization | The support Agent may refund up to $100 per Invoice. |
A person changing Roles gains and loses Permissions at once. A Customer that cancels loses its Entitlements at the end of the paid Period. Nothing is granted by a screen: hiding a button is design, not access control.
Limits become Approvals
A Limit bounds an amount, a count, or a rate over time, and api.sb checks it before every call. An Agent, a person, and a scheduled Workflow meet the same check.
A call over its Limit does not fail. It waits as an Approval, a Task for a Worker with the authority to allow or refuse it. The support Agent's $250 refund waits for a person; its $40 refund runs at once.
Customers and their teams
People from a Customer sign into the Startup's App and see only their own Tenant. A Customer that is an Organization connects its own single sign-on and directory. Its people then join and leave the Tenant as they join and leave the Organization.
Because api.sb checks every call, every Interface enforces the same rules. A Customer reading reports over MCP sees exactly what the Portal shows them.
| Term | Kind | Definition |
|---|---|---|
| Security | Process | Security keeps every Permission earned, every secret fresh, and every access recorded. |
| Access Level | Noun | An Access Level is a named preset of Permissions a Worker holds in a namespace, such as owner or viewer; it is never a Role. |
| API Key | Noun | An API Key is a secret a Startup issues to one Customer, which signs that Customer’s calls to its API, SDK, CLI and MCP server. |
| Approval | Noun | An Approval is a Task to allow or refuse one pending Action that exceeds a Limit or a Mandate. |
| Entitlement | Noun | An Entitlement is what a Customer gets from an accepted Offer: a Verb on a Noun in its Tenant, optionally bounded by a Limit. |
| Human | Noun | A Human is a Worker who is a person, acting on Tasks through Apps, Mailboxes, and Channels. |
| Limit | Noun | A Limit is a bound on a Permission, Entitlement, or Mandate, checked before every call; exceeding it creates an Approval. |
| Mandate | Noun | A Mandate is a standing authorization for an Agent to act for a Party, within Permissions and Limits, until it expires. |
| Permission | Noun | A Permission is what a Role may do: a Verb on a Noun within a scope, optionally bounded by a Limit. |
| Person | Noun | A Person is a human with one identity across every Startup; each Startup’s Contact is its own view of that Person. |
| Tenant | Noun | A Tenant is the partition of a Startup’s data that belongs to one Customer. |
| APIKey.issue | Verb | Issue creates an API Key for one Customer and returns its secret once; afterwards only the prefix shows. |
| APIKey.revoke | Verb | Revoke stops an API Key at once: its next call fails with 401, and the record and its history stay. |
| APIKey.roll | Verb | Roll issues a replacement API Key with the same scope and keeps the old one working until a set time. |
| Approval.approve | Verb | Approve allows the pending Action an Approval holds, and that Action runs. |
| Approval.refuse | Verb | Refuse declines an Approval, which sets the Action it holds to refused with the reason given. |
| Entitlement.check | Verb | Check says whether a Customer may call a Verb now, how much of its Limit remains, when that resets, and which Offer lifts it. |
| Human.invite | Verb | Invite asks a person to join a Startup in a named Role, sharing that Role’s work with its Agent. |
| Human.onboard | Verb | Onboard admits a recruited Human to supply work once their identity, Credentials and payout details verify. |
| Limit.raise | Verb | Raise lifts a Limit after an Approval allows it, and the Action that waited on it proceeds. |
| Mandate.authorize | Verb | Authorize grants an Agent a standing Mandate to perform a Verb within a Limit, without asking each time. |
| Mandate.pause | Verb | Pause stops every new Action under a Mandate at once and keeps its scope, so it can resume unchanged. |
| Mandate.resume | Verb | Resume restarts a paused Mandate with its scope, Limits and approval rule unchanged. |
| Mandate.revoke | Verb | Revoke ends a Mandate at once, so new Actions under it are refused and running ones finish. |
| Offer.grant | Verb | Grant adds an Entitlement to an Offer: a Verb its Customers may call, optionally bounded by a Limit. |
| Startup.claim | Verb | Claim binds a provisional Startup to a verified owner, which enables payments and every Verb that moves money. |
| Tenant.invite | Verb | Invite asks a Person to join a Customer’s Tenant, and resizes the Subscription when the Offer prices per member. |
| Tenant.provision | Verb | Provision creates a Customer’s Tenant in a Startup’s App, holding that Customer’s records apart from every other. |
Next
- Workflows: how an Action waits for an Approval and resumes.
- Permission: the full reference.
- Errors: every error a refused call returns.