Connection
A Hyperapp facet — the agent's own authorized access to an external service the Hyperapp fronts; the app and trigger facets build on it.
1. Purpose
A connection is the agent's authorized access to an external service.
The Hyperapp is the service's third-party client — the GitHub Hyperapp is a client of GitHub — and its connection binds the service's access to the agent, under an identity a human authorizes. The agent then acts on the service, as that identity, through the Hyperapp.
Wherever the service allows it, the connection gives the agent its own identity — its own app, or at least its own token — so agents stay isolated: separate credentials, separate revocation, the app living under the user's own account. A shared identity is used only where the service cannot grant a distinct one.
The result is a grant: the external identity and its credential, bound to the agent. A human performs the authorization out-of-band, and the agent — which holds no external credential of its own — acts through the grant the Hyperapp carries.
The agent acts on the service through the connection — the app facet reads and writes with it.
A connection is distinct from Hyperauth: Hyperauth is who the agent is within Hypernet, verified on every request; a connection is the agent's access to an external service, set up once and bound to it. Internal identity vs. an external grant — two distinct layers.
2. Roles
| role | does |
|---|---|
| a human (operator) | establishes the connection — creates / authorizes the app, installs it |
| the agent | the grant is scoped to it; it later acts through it |
| the external account | what the grant reaches |
Connecting is a human, out-of-band action — not the agent's; a connection is therefore not part of the app facet. The connection is inherently to the service the Hyperapp fronts — the GitHub Hyperapp's connection is to GitHub — so the provider is implied.
3. Methods
The declaration names a method — how the human establishes the connection — and the platform renders the matching UI. The methods differ in how isolated an identity the agent gets:
- manifest — the agent gets its own app on the service. The human is redirected to create an app under their own account, from a template the Hyperapp provides; the service returns the new app's credentials, which become the grant. The most isolated — a distinct app, credentials, and webhooks per agent. (GitHub's App Manifest.)
- oauth — the agent gets its own token under a shared app. A redirect authorize: the declaration carries an authorize URL, the platform opens it, and a callback turns the authorization into a grant.
- form — the human fills the fields the declaration carries and submits them to the Hyperapp. Used for an API key, or — where a service has no redirect flow but a per-agent app is still possible — a manifest and instructions the human follows to create the app by hand, then pastes its credentials. (Slack.)
The order is the fallback order: prefer a per-agent app (manifest), then a
per-agent token (oauth), then per-agent credentials entered by hand (form); a
service that can do none of these shares one identity. Every method converges on a
grant scoped to the agent, holding whatever the method produced.
A method may take more than one step — create an app, then install it. The
Hyperapp drives this from record: a step that returns a next URL tells the
platform to open it and record again, until no next remains. The platform
sequences the steps; each step's meaning is the Hyperapp's.
4. Surface
A Hyperapp's connection facet exposes:
- a declaration —
{ title, description, icon, authorize }— the card and the method: for a redirect method (manifest/oauth)authorizecarries the URL to open; forform, the fields (with any instructions and template); - a callback a redirect method returns through, and a record endpoint the
platform posts each step's result to — record stores the grant and may return a
nextURL to continue; - a status — is this agent connected?;
- a revoke — drop the grant.
5. Storage
Recording a connection produces a grant scoped to the agent — provider- agnostic and opaque: a per-agent app's keys, an OAuth token, or an API key (encrypted). Where the grant lives is the Hyperapp's choice: the platform offers Hypervault, the credential vault, or the Hyperapp keeps its own store. Either way the Hyperapp acts on the service itself — it reads its grant and mints or presents the credential, and a trigger verifies the service's events with that same grant's per-agent secret. Credentials and provider logic never centralize in a shared service.