Technical Components

Vana Connect

Vana Connect is the embeddable modal that handles the user-facing data connection flow for personal data from any source.

What happens inside Vana Connect:

Source selection — User picks which service to connect (Instagram, Spotify, etc.)
Permission preview — User sees exactly what data will be shared (e.g., "Flipboard wants: Your profile info and liked posts")
Hosted login — User authenticates directly to the source through Vana's secure session
Progress & completion — User sees extraction progress and confirms when complete

The modal is mobile-web-first, requiring no browser extensions, apps, or client-side installations. Everything runs server-side.

Session APIs

Builders use session APIs to initiate and track Vana Connect flows:

Method	Endpoint	Description
POST	`/v1/sessions`	Create a new connect session (returns `session_id`, `redirect_url`)
GET	`/v1/sessions/{session_id}`	Get session status (`pending`, `in_progress`, `completed`, `failed`)
DELETE	`/v1/sessions/{session_id}`	Cancel a session

Ingestion Engine

The Ingestion Engine handles data extraction from user-authenticated sources. When a user logs into their Instagram or Spotify through Vana Connect, the engine:

Spins up a secure, isolated browser session on Vana's servers
Navigates to the pages needed for each requested scope
Extracts data into a defined, predictable structure
Returns structured data to the user's Vault

Key capabilities:

Server-side execution — No code runs on the user's device; all extraction happens on Vana infrastructure
User takeover for authentication — Users handle their own login, CAPTCHA, and 2FA; Vana never auto-solves or stores credentials
Structured output — Data is returned in defined schemas per source and scope
Session isolation — Each extraction runs in an isolated browser instance with automatic cleanup

Remote Browser API

The Ingestion Engine exposes APIs for managing browser sessions during the connect flow:

Method	Endpoint	Description
POST	`/sessions`	Create new browser session, returns `sessionId`, `token`, `wsUrl`
GET	`/sessions/{id}`	Get session status
DELETE	`/sessions/{id}`	Terminate session, cleanup resources
POST	`/sessions/{id}/run`	Execute a precompiled extraction script
POST	`/sessions/{id}/takeover/complete`	Signal that user finished manual interaction (login, 2FA)
WebSocket	`/sessions/{id}/ws`	Real-time events: status updates, progress, screencast frames
GET	`/scripts`	List available extraction scripts and their parameter schemas

Design principles:

Scripts run server-side only—no code injection from frontend
WebSocket is read-only—frontend receives events but never sends commands (except takeover signals)
Every session gets a cryptographic token; all requests are authenticated
Sessions auto-expire after 5 minutes with guaranteed cleanup

Data Vault

The Data Vault is the user's personal data storage layer—the "account" where all connected data lives.

Design principles:

Multi-source — Data from Instagram, Spotify, ChatGPT, and other sources all live in one vault
Versioned — Each extraction creates a new snapshot with a timestamp; users can refresh data anytime
Raw storage — Data is stored as-is with no heavy processing; builders receive it in known schemas
Permissioned — Different builders can receive different slices of the vault based on granted scopes

Vault Dashboard

Users manage their data at vault.vana.com—a personal dashboard for complete visibility and control:

View connected sources — See all services linked to their vault
Manage active grants — See which apps have access to which data
Revoke access — Instantly cut off any app's access
Refresh data — Trigger a new extraction to update stored data
Browse data — See exactly what's in their vault
View audit log — See every data access event
Request deletion — Remove data from the vault entirely

User APIs

Users (and apps acting on their behalf) can manage vault data programmatically:

Method	Endpoint	Description
GET	`/v1/me`	Get current user profile
GET	`/v1/me/grants`	List all grants the user has issued
DELETE	`/v1/me/grants/{grant_id}`	Revoke a grant
GET	`/v1/me/sources`	List connected data sources
GET	`/v1/me/audit-log`	Get user's data access history

Permission Model: Scopes & Grants

Scopes

Permissions work like OAuth scopes, not file-level access controls. Builders request specific data types, and users approve or deny.

Scope structure: source.data_type

Scope	What it returns
`instagram.profile_info`	Username, bio, avatar, follower counts
`instagram.posts`	User's own posts with captions, timestamps, engagement
`instagram.liked_posts`	Posts the user has liked
`instagram.comments`	Comments the user has made
`instagram.ads_targeted`	Ads shown to the user with targeting categories
`spotify.listening_history`	Recently played tracks and artists
`spotify.playlists`	User's saved playlists

Each scope has a defined TypeScript schema, so builders know exactly what data structure to expect. Future sources follow the same pattern: source.scope_name.

Grants

Grants are wallet-signed permissions that provide cryptographic proof of user consent.

How grants work:

User connects a source and approves requested scopes
User's wallet (created invisibly during account setup) signs the permission
Grant is recorded with the exact scopes, timestamp, and builder ID
Grant signature cannot be forged or modified after creation

Grant verification happens on every data request:

1. App calls GET /v1/grants/{grant_id}/data
2. Vault verifies:
   - grant_id exists and is not revoked
   - request is authenticated with valid client_secret for this app
   - requested scopes are subset of granted scopes
   - grant has not expired
3. If valid → return scoped data
4. If invalid → 403 Forbidden with reason