eyeballdocs
Concepts

Connected accounts

Map external users to provider accounts and understand the development-vault and cloud-vault boundary.

external_user_id—userId in the SDK—is your stable application identity. The connection resolver combines it with project and toolkit to select a provider account.

Text
project + external user + toolkit + optional connectionId
  → authorized provider credential

Lifecycle

The hosted connect flow is conceptually:

  1. Your server requests a connection for a toolkit and external user.
  2. The user completes provider consent at a hosted redirect.
  3. The hosted vault marks the connection connected and refreshes credentials.
  4. Revocation, expired consent, or missing scopes surface as normalized auth errors and require reconnection.

The checked-in SDK's connections.create response currently models only a connected development fixture: { connectionId, redirectUrl: null, status: "connected" }. Hosted redirect and lifecycle types belong to eyeball Cloud and are not claimed by the open-source API.

Development vault

The optional OSS development vault is:

  • process-local and reset on restart;
  • intended for non-secret mock fixture data;
  • available only when explicitly mounted by the executor;
  • scoped by project and user like normal connections.

Self-hosted real credentials

The stock OSS executor also resolves real provider credentials without the hosted connect flow. Select a source with EYEBALL_CREDENTIALS:

  • env maps EYEBALL_CRED_<TOOLKIT>_* variables for a single project and user; it does not refresh OAuth tokens.
  • local-vault stores many users under one project in an AES-256-GCM file, connected with the eyeball-auth CLI, and refreshes credentials that carry an expiry.

Both resolve through the same project + external user + toolkit path above. See Connect real providers.

Cloud vault

The private Cloud source owns hosted OAuth callbacks, encrypted refresh-token storage, consent repair, and connect UI. Those services are outside the open-source repository and are not claimed as deployed or live-provider certified.