Connection, pairing and scopes
Obtain explicit access and negotiate a local native-client session.
AlphaDiscovery identifies the active Host endpoint and identity. It does not authorize access, and a client cannot approve its own pairing request.
Pair
Read the current discovery file with ApiHostDiscovery.ReadAsync, construct StreamingHubApiClient(discovery), and call RequestPairingAsync with a stable client ID, claimed display name/publisher and requested scopes.
The user approves or denies through Core's tray. Poll the returned handle with PollPairingAsync; only an approved result returns the credential, once. Connect using ConnectWithCredentialAsync and the required capabilities.
Store a retained credential using protected local storage. Keep credentials, sessions and pairing handles out of logs, URLs, command lines and project files.
Pairing requests expire after two minutes; at most 16 can be pending. Credentials last 30 days and are bound to the stable client ID. HTTP sessions last at most two minutes, bounded by credential expiry. Exchange a still-valid credential again and complete handshake to renew without changing grants. Client names and publisher labels are claimed text, not verified publisher identity.
The PowerShell walkthrough includes every HTTP request. Your first .NET client implements the same flow with typed methods.
Select permissions
| Scope | Purpose |
|---|---|
host.status | Host identity and safe status |
host.shutdown | Explicit Host shutdown; separate from status access |
project.read / project.configuration.read | Structural state / content-bearing configuration |
project.write / project.files | Apply and recovery / project file operations |
catalog.read | Declared actions, signals and schemas |
settings.read / settings.write | Plugin/Core settings and versioned writes |
runtime.read / runtime.control | Runtime observations/recovery and execution control |
runtime.values.read | Live variables, service values and statistics |
diagnostics.read | Bounded diagnostic metadata |
diagnostics.content.read | Sensitive diagnostic/log content and sanitized signal samples |
inspector.read | Bounded traces for the selected run, subject to ownership |
history.read / history.manage | Persisted run data / retention and clear |
updates.read / updates.manage / updates.prepare | Update observations, exact-plan control and client preparation |
plugins.trust.read / plugins.trust.manage | Trust candidate reads / decisions |
interaction.read / interaction.respond | List pending interactions / claim, release and respond |
components.read / components.install | Read installation component catalog / plan installation |
project.layout.read / project.layout.write | Retired; layout is client-local and routes return editor_layout_local |
Some methods require combined scopes. Runtime value reads, sensitive diagnostics and interaction responses have additional dedicated permissions; inspect the negotiated capabilities and method contract.
Dynamic editor options require catalog.read, project.configuration.read and settings.read together. Context-file pickers require project.files. Reading a catalog does not grant directory access. Responding to sensitive interactions also requires the underlying operation's scope. Runtime control does not grant runtime command-result reads.
Handshake's requiredCapabilities selects capabilities from the approved grant and rejects unavailable ones. Keep that list explicit. An application providing only status should request host.status; one that reads a project adds project.read; one that applies edits also needs project.write. Do not copy the supplied Editor's full grant into every client.
Renewal cannot expand a grant. A disconnected session can reconnect using an unrevoked credential; revoked or expired access must be resolved explicitly. A fresh pairing is a different principal for command recovery.
Disconnecting one session does not revoke its approved credential. Revocation invalidates associated sessions and subscriptions. Core's trusted client-access controls own these administrative actions; there is no public HTTP approval endpoint for a client to authorize itself.
Browser boundary
The current API accepts local native clients. Core does not enable a LAN listener, CORS or browser-origin access. Do not expose it through a web proxy as a substitute for an approved browser security design.