# Developer portal (/docs/app/developer-portal)

> Study: a study of the work. Defines nothing. No package exists.

> App study: where a Customer's developers, payers and agents get a key, make a first call, fix failed calls and read their own analytics.



A developer portal is the App where a Customer builds on a Business's API, Dataset, SDK or agent endpoint. It has two halves of equal weight. The account plane gets the Customer in, fixes failed calls and takes payment. The Customer's own analytics says what was used, in which unit, its projected cost at period end, and what the product delivered and refused.

It is a projection of the API, not a layer over its own tables. Every control is a Verb the API exposes, and every figure is a reading the gate and the books also use.

Any Business that sells programmatic access ships one: a data vendor, a payments company, a law firm with an API. startupbuilder.dev once named this App kind Dashboard; a [Dashboard](https://next.mdxui.dev/docs/components/dashboard) is now the View this App renders, not the App. The study describes the work; how an App is defined is open, see [What every App needs](https://next.mdxui.dev/docs/app/every-app).

## Actors

| Actor | Side | Work here |
| --- | --- | --- |
| Developer | Customer | Reaches a first 2xx, then keeps it working: keys, logs, webhooks, Test |
| Coding agent | For the developer | Reads the docs and machine registers, mints a Test key, calls, reads the log, wires the integration |
| Runtime agent | For the Customer, under a Mandate | Calls live and tops up within its ceiling |
| Account owner | Customer | Accepts the Offer, signs Mandates, closes or transfers the account |
| Admin, payer, viewer | Customer | Team, spend caps, plan; invoices and receipts read-only |
| Assurance reader | Customer, often a clinical or compliance lead | Reads release gates and data provenance; signs off a Version for go-live |
| Outside implementer | Customer, invited | Works in a sandbox with no access to live data |
| Sub-tenants | The Customer's own customers | Exist for platform Customers; their usage embeds in the Customer's App |
| Support, risk, founder | The Business | Read the same records from [Admin](https://next.mdxui.dev/docs/app/admin), never from here |

One person often holds owner, developer and payer on day one. A design that merges them breaks at the second person.

## Interfaces

| Reader | Screens | Renderings |
| --- | --- | --- |
| Anyone, before sign-in | Pricing from the same record the gate enforces; docs; a keyless capped call; an anonymous sandbox; status; changelog | `llms.txt`, OpenAPI, Markdown per page, MCP docs, a prompt for the reader's agent |
| Developer | First run (key, call, see it land); keys; request log with refusals grouped by what refills them; webhooks with deliveries; Test mode; version; an object inspector for stateful APIs | Response headers (`X-Request-Id`, `X-Cost`, rate-limit headers); problem documents with a cure; MCP tools; CLI login by OAuth |
| Every Customer reader | Usage per API in each counting unit against each Limit, over a declared window; cost so far and a typed projection to period end; what this period would cost on another Offer; bill lines explained by their Events; free and refused acts; outcomes; delivered reports with their run receipts; spend alerts | The same readings as Markdown and JSON |
| Owner, admin, payer | Offer; billing; credits; team; Mandates and pending Approvals; Credentials for access-gated Offers; compliance; settings with every "view as" entry the Business's operators left | Email for key created, key leaked, spend milestones, past due, invoices, endpoint failing, deprecations |
| Customer admin, for its agents | Tools the Business exposes, with scope and side effects; agent seats with who deputized each; the approval policy for side-effecting tool runs; traces per session | |
| Data product Customer | Sharing: active and revoked grants to partners, the share composer, stop sharing, sealed exports | |
| Assurance reader | Release gates with measured values for the pinned Version; dataset provenance; audit export; sign-off | |

The analytics half is a set of Dashboards, each a View of one Customer's scope rendered as screens, Markdown and JSON. What only this type adds is the content: counting units against Limits, a projection to a billing boundary, and outcome classes that are also money.

Analytics sold as the Product, such as scheduled market reports to a Customer's Slack, is an Offer delivered here and through channels, not a separate App.

## Records and actions

The type has no single dominant record. It is a cluster of small lifecycles around one Customer account. For a stateful API, the API's own work record joins them at the center: a matter, a claim, a pallet's chain of custody. Its performer may be a human or an agent, doing digital or physical work.

| Record | States |
| --- | --- |
| Account | anonymous, identified, verified, delegated; new, keyed, activated at the first 2xx, active; over a Limit, trialing, scheduled to cancel, past due, dormant, closed |
| Key | revealed once, active, rolling with grace, revoked or expired; Test or Live |
| Call | received, allowed or refused, served, rated, billed or not billed |
| Refusal | clock (429 with a retry time), settlement (402 with a checkout cure), human (403 with a claim or Approval link) |
| Reading | present, unavailable, partial, early; a projection typed early, metered, capped or contract |
| Webhook delivery | first try, retrying, succeeded or exhausted, sent again |
| Subscription, Invoice, credit balance | startupbuilder.dev's states; a credit balance runs funded, low, empty, topped up |
| Mandate and Approval | active, near ceiling, Approval pending, expired or revoked |
| Sharing grant | active, revoked and kept as evidence |
| Version pin | pinned at the first call, upgrade available, testing, upgraded, rolled back, sunset |

The Verbs group by record. Account: claim, answer, leave, close. Key: create, reveal once, roll, revoke, scope, tag as agent. Webhooks: create, send again, replay since, rotate secret.

Money: accept an Offer, switch, cancel, resume, add credits, set a cap. Agents: grant a tool scope, deputize, approve a tool run. Sharing: share, stop sharing. Version: pin, test an upgrade, roll back.

### Terms

| Term | In startupbuilder.dev | Definition, quoted from [startupbuilder.dev](https://startupbuilder.dev) or the gap |
| --- | --- | --- |
| Customer | [Customer](https://startupbuilder.dev/business/nouns/customer) | "A Customer is a party that has accepted an Offer from a Startup at any price, including zero." Read for any Business. |
| Limit | [Limit](https://startupbuilder.dev/business/nouns/limit) | "A Limit is a bound on a Permission, Entitlement, or Mandate, checked before every call; exceeding it creates an Approval." |
| Mandate | [Mandate](https://startupbuilder.dev/business/nouns/mandate) | "A Mandate is a standing authorization for an Agent to act for a Party, within Permissions and Limits, until it expires." |
| Dashboard | [Dashboard](https://startupbuilder.dev/business/nouns/dashboard) | "A Dashboard is one unified view of a scope, rendered as Markdown for Agents, screens for Humans, and JSON for native clients." Each analytics View here is one; the App is not. |
| Access Level | [Access Level](https://startupbuilder.dev/business/nouns/access-level) | "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." A Customer's members are not the Business's Workers, so this type has no access unit for them. |
| Credential | [Credential](https://startupbuilder.dev/business/nouns/credential) | "A Credential is a standing authority a regulator grants a person or entity to perform certain acts in a jurisdiction." It covers supply; a buyer's credential that gates access is a gap. |
| API key, Test twin, call record, delivery | lack | startupbuilder.dev withdrew its key Noun and has a mode, not a twin. |
| Counting unit, projection kind, sharing grant | lack | |

## Workflows

1. **Stranger to first 2xx.** A pricing choice rides through sign-in. The key is revealed once inside a snippet, the call lands live, and onboarding completes at the first call, not at signup.
2. **Agent first.** An agent calls keyless within a free allowance, mints a Test key and scripts against fixtures. It may pay for reversible scope, such as data or sandbox calls, where the Business allows it. Any scope that carries a legal agreement waits on a human signer through a link that shows the worst case in dollars.
3. **Call, inspect, fix.** A refusal carries its class and cure. Errors group by code, each with a docs page and a Test trigger. "Ask support about this request" carries the request id.
4. **Read, project, alert.** Usage reads in the unit the Offer bills, over a window that names its source: the billing period or the calendar month. A projection is a straight line labelled as one, never shown under a day. A spend alert informs and never limits, and a failed read renders "Usage unavailable", never zero.
5. **Govern the Customer's agents.** The admin grants tool scopes, deputizes agents with a ceiling and an expiry, and sets which tool runs need a human. Each approval binds to the hash of what was shown.
6. **Regulated go-live.** Test works at once; live waits on a business profile in third-party review, a buyer's credential, or the assurance reader's sign-off. The portal names who must act next.

## Boundaries

- The Organization is the partition, and keys belong to it, not to a member. A member who leaves breaks nothing.
- The Business's operators never see key values, request bodies, webhook payloads or payment details. A "view as" needs a reason, is time-boxed, and leaves an entry the Customer reads.
- A deputized key's rates are a rate on the deputizing person, so they render to that person and the owner only.
- Embedded usage for sub-tenants takes the tenant from the authenticated principal, never from a parameter alone.
- Stopping sharing stops future reads and cannot recall data a partner already pulled; the control says so.
- One identity across many Businesses on one platform never reveals to one Business that the Customer buys from another.
- The App's owner and its screens' owner can differ. A portal shared across a family of Businesses carries each Business's domain Views in named slots, under that Business's Brand only.

## Agents

| Step | Agent alone | Human |
| --- | --- | --- |
| Discover, quote, call keyless, mint Test keys, fix errors in Test | yes | |
| Read every analytics View as Markdown or JSON | yes | |
| Pay for reversible scope | where the Business allows | sources disagree on whether money waits for a claim |
| Accept terms, claim the account, present a credential | no | legal and financial principal |
| Spend within the Mandate | yes | |
| Spend above the approval line; side-effecting tool runs under the Customer's policy | no | approves by link before a deadline |
| Grant tool scopes, deputize an agent, share a record outward | no | an admin |
| Sign off a Version for go-live | prepares the evidence | a named person |
| Close the account, change the owner | no | the Owner, inside a delay window |

## Hard parts

1. **One source of truth for price, Limit, refill and state.** The portal, the gate, the books and the SDK read one row per rule, or they drift within days.
2. **Counting units are separate Metrics.** Requests, raw calls and billable calls diverge on repeat lookups. A tile with one unit under another's label is a lie about money.
3. **Unavailable is not zero.** A page a suspended Customer needs to pay is never taken down by a usage read that throws.
4. **One bound, two refills.** A monthly cap is refilled by the clock and by an upgrade; the refusal needs one status and may carry two cures.
5. **Exactly-once metering.** Late and out-of-order events, Limits checked before every call, counters shown later, and every bill line explainable.
6. **Governing someone else's agents.** Scopes per tool, approvals bound to a hash, traces under one request id, and policy that retrieved text cannot change.
7. **Assurance has a basis.** A gate not run never shows as passing, and a synthetic suite says so.
8. **The state explosion.** Account states, refusal classes, reading presence and work-object waits multiply across screens. A matrix that derives states from gate outcomes, and fails on a missing one, is the specification.

## Day one

Before any portal, a Business publishes docs, machine registers, pricing, a capped keyless call and an MCP server under its own Brand, with a checkout link for prepaid credits.

The first Customer needs:

- sign-in with one owner, and a first run;
- keys with a Test twin;
- usage in the unit the Offer bills, over a declared window, with a typed projection and an honest "unavailable";
- credits always shown, and the 402 with a checkout cure;
- the request log, with refusals grouped by refill class;
- support prefilled with the request id, and an account brief an agent can read.

| Trigger | Turns on |
| --- | --- |
| A subscription Offer | Invoices, cancel and resume, past due |
| A second person | Team and invites, waiting on an access unit for a Customer's members |
| Sustained traffic | Spend alerts, Customer-set caps, bill lines explained |
| Agents buy | Mandates, Approvals, MCP sessions, child keys |
| The Customer's agents call side-effecting tools | Tools, approval policy, traces, agent activity |
| A Report or analytics Offer | Report subscriptions, runs and receipts |
| A data product with partners | Sharing and sealed exports |
| A regulated or credentialed buyer | Credential gates, the assurance reader, sign-off |
| Work behind the call | Work-object Views with pending reasons; physical steps with Place and evidence |
| Platform Customers | Sub-tenants and embedded usage |

A Startup reaches this type first because its first Product is so often an API. An established Business often needs the later rows first: contracts, SSO, roles, audit, migrated keys and, in regulated domains, the assurance reader.

## Related studies

## Prototypes this study needs