Interfaces
The interfaces that reach an app's methods (web, API, MCP, agent, voice, cron, webhook, email, task), each with its trigger, its auth, and where it enters, all invoking the same methods through one execution path.
An app's methods are its backend contract. Interfaces are the ways the outside world reaches that contract: a web app, a REST API, an MCP tool server, a conversational agent, a voice line, a cron schedule, a webhook, an inbound mailbox. Every interface invokes the same methods through the same execution path, and a method does not know which interface called it. This chapter covers each interface at the infrastructure level: its trigger, its auth, and where it enters the platform.
#The Matrix
| Interface | Trigger | Auth | Enters at | Runs as | Sandbox |
|---|---|---|---|---|---|
| Web | Browser on the app's origin | App session cookie, or guest | serve and proxy on the HTTP role | The signed-in app user or a visitor | Interactive, warm |
| API | HTTPS request | App API key as bearer | /_/api/... on the app origin, or the platform API host | The key's owner | Interactive, warm |
| MCP | An MCP client | OAuth token from the app's own authorization server, or an app API key | /_/mcp on the app origin | The caller | Interactive, warm |
| Agent | A chat turn from the browser | App session or guest | /_/agent/... | The user; methods as tools | Interactive, warm |
| Voice | A phone call or a browser session | Per-session credential from the voice worker | The voice serve routes | The caller; methods as tools | Interactive, warm |
| Cron | A schedule | None; system invocation | The dispatcher on every HTTP pod | The system user | Background, held until its next run when that is soon |
| Webhook | An external POST | The webhook's configured secret | /_/webhook/... | The system user | Interactive, warm |
| An inbound message | None; system invocation | SMTP on the mail-inbound role | The system user | Background | |
| Task | A model loop that a method's code starts | Hook token | The task routes | The identity of the method that started it | Interactive, warm |
Each interface is declared in the app's manifest and compiled at build time to exactly what its surface reads. A running surface reads its configuration from the release answering the request, so a deploy changes a route or a mailbox by changing which release answers. Cron is the one exception, because a scheduler needs a row to fire from: its schedule is reconciled into the app's cron registry at promotion, job by job. See Build and Deploy.
#Web
The web interface is the app's frontend build, uploaded per release and served from the app's origin with the session injected. Its calls to the backend go under the internal methods path and are dispatched by the segment switch. Mounted child apps, web routing rules, and embedding origins are validated at build. The interface is safe by construction: nothing real happens in it, because every mutation is a method call the platform authorizes.
#API
The API interface exposes methods as REST routes. Callers authenticate with per-user API keys the app issues: shown once, stored as a hash, revocable, and displayed masked. A key can be sent as a bearer token or as the password of Basic auth, the form git's credential helpers store. The same routes answer on the app's origin and on the platform's API host with the app named in the path, which is what the dev box's tunnel and the editor use in development.
A route answers with the method's output as JSON, unless the method returns an HTTP response of its own: a status, headers, and a text or binary body, a redirect, or a stored file. Only this interface and the webhook interface send one. On any other door it is a method error, so a method's data stays the same answer everywhere.
A stored file never passes through a pod. The API service answers with a marked redirect to a short-lived signed URL, and on the app's host the edge Worker follows it and streams the bytes back at the request's own URL (see Edge and Custom Domains). A route's last segment may be a wildcard that takes the rest of the path. This lets an app serve a tree of files, including a git repository over git's plain HTTP protocol, with its own auth and its own log of every read.
#MCP
The MCP interface exposes the methods the manifest selects as tools, with schemas derived from the method signatures. An MCP client connects to the app's origin, lists tools, and calls them; each call is a method invocation with the caller's identity. A downloadable skill document describes the tool set so an agent can be pointed at the app.
The app is its own OAuth 2.1 authorization server for those clients. Its issuer is the app's origin. Its discovery documents answer under the standard well-known path on that origin, and the edge routes those two paths to the API service. Its authorize, token, and revocation endpoints sit under the app's OAuth path.
A tool call that needs a signed-in user and has none is answered with a 401 carrying the standard challenge, which sends the client to the authorize page. That page shows the app's own sign-in methods, rendered by the platform with the app's name and icon, followed by consent.
- Clients identify themselves by Client ID Metadata Document, so there is no registration step. Clients that publish keys sign their token requests with them.
- PKCE S256 is required, and there is one scope.
- Every token is bound to the MCP endpoint on the origin it was issued on.
Tokens are opaque and resolve to the app user at each call, as sessions and API keys do. A revoked grant or an offboarded delegated user therefore stops at the next request. The grants are rows in the app user data in Aurora; the pending requests, codes, and access tokens are Valkey entries.
#Agent
The agent interface is a conversational front end over the methods. The platform runs the agent loop in the model service with the app's methods as tools, streams the response, and persists threads per user. Data sources reach the agent through the methods it calls. The agent's model and configuration are compiled from the manifest and projected from the release each request is answered by, and the workspace's model and vendor controls apply.
#Voice
The voice interface puts the same methods behind a phone number or a browser call. See Voice.
#Cron
A cron interface is a schedule and a method, with at most one fire a minute. Promoting a release writes the schedule to the job table, and a release without the interface removes it. A dispatcher on every HTTP pod claims due jobs with row-level locking that skips already-claimed rows, so pods compose rather than race. Each run is a system invocation on the release's pod as background work, finalized exactly once, with missed ticks coalesced after an outage and a per-workspace concurrency cap. Consecutive failures pause a job; platform-side failures do not count against it.
#Webhook
A webhook interface is a route and a method. The platform verifies the configured secret and runs the method as a system invocation on a warm sandbox, because webhook senders enforce response latency. The method's output goes back as JSON, or as an HTTP response of its own where the sender expects one: TwiML, or a plain-text challenge echo.
An email interface is an address on the app's subdomain and a method. The mail-inbound role accepts the message over SMTP, resolves the app from the recipient, and runs the method as a system invocation, as background work, with the parsed message as input. See Email.
#Task
A method's code can start a task: a model loop that runs in the method's own process and is served by the platform one turn at a time, with steps, the app's methods, and inline functions as tools. A task has no identity of its own. It runs as the method that started it, with that method's user, roles, and world, one level deep, and returns its structured output to that code. An agent reaches a task only through a method it calls.
``` Figure 27, "Interfaces": one backend, many doors. Left: a column of nine interface doors, each labelled with its trigger and its authentication. Web (browser, session or guest) · API (HTTPS, per-user API key) · MCP (client, OAuth token or key) · Agent (chat turn, session or guest) · Voice (call, per-session credential) · Cron (schedule, system) · Webhook (external POST, shared secret) · Email (SMTP, system) · Task (started by a method's code, hook token). Cron and Email carry a second line, "background"; the rest are interactive and warm. The nine doors feed a collector that lands on one heavy node on the right, "The methods": the app's backend contract, reached through one authorization and one execution path, so a method does not know which door it came through. A header over the column notes that all nine are declared in the manifest and compiled at build to what each surface reads from the release answering the request. One side arrow, "cron: reconciled into the cron registry at promotion", marks the single exception. A cross-reference points to Figure 15 for the execution path each door lands on. No trust boundary is drawn in this figure, so there is no crimson.