Builder Integration

This section outlines the developer-facing side of Data Portability, so the SDK, API endpoints, webhook events, and response formats. It covers how applications interact with the system to manage apps, initiate connections, retrieve user data, and manage notifications.

Portability SDK

Builders integrate via a simple SDK:

Client-side (few lines of code):

import { VanaConnect } from '@vana/connect';

const connect = new VanaConnect({
  clientId: 'your_client_id',
  scopes: ['instagram.profile_info', 'instagram.liked_posts'],
  onSuccess: (result) => {
    // result contains scoped data
  }
});

connect.open();

Server-side (fetch data with authenticated requests):

GET /v1/grants/{grant_id}/data
Authorization: Bearer {client_secret}

Builder APIs

All endpoints at api.vault.vana.com, authenticated with client_secret:

Method	Endpoint	Description
GET	`/v1/grants/{grant_id}`	Get grant details (scopes, status, created_at)
GET	`/v1/grants/{grant_id}/data`	Get scoped data for a grant (with verification)
GET	`/v1/grants/{grant_id}/data/{scope}`	Get data for a specific scope only
POST	`/v1/grants/{grant_id}/refresh`	Trigger data refresh (re-extraction)
GET	`/v1/webhooks`	List registered webhooks
POST	`/v1/webhooks`	Register a webhook URL

Admin APIs

For app registration and management:

Method	Endpoint	Description
POST	`/v1/apps`	Register a new app (returns `client_id`, `client_secret`, `webhook_signing_key`)
GET	`/v1/apps/{app_id}`	Get app details
PATCH	`/v1/apps/{app_id}`	Update app (name, redirect_uris, scopes, etc.)
POST	`/v1/apps/{app_id}/submit`	Submit app for review (draft → in_review)
POST	`/v1/apps/{app_id}/rotate-secret`	Rotate client_secret

Webhooks

Builders can register webhooks to receive real-time notifications:

Event	When it fires
`grant.created`	User completes connection and signs grant
`grant.revoked`	User revokes access via their dashboard
`data.refreshed`	User triggers a data refresh

Example Response

When a user connects Instagram with profile and liked posts scopes:

{
  "success": true,
  "scopes": ["instagram.profile_info", "instagram.liked_posts"],
  "data": {
    "profile_info": {
      "username": "johndoe",
      "fullName": "John Doe",
      "bio": "Software engineer. Love cooking and travel.",
      "avatarUrl": "https://...",
      "followersCount": 1234,
      "followingCount": 567,
      "postsCount": 89
    },
    "liked_posts": [
      {
        "id": "abc123",
        "ownerUsername": "techcrunch",
        "caption": "Breaking: New AI breakthrough...",
        "timestamp": "2026-01-07T10:30:00Z"
      }
    ]
  },
  "metadata": {
    "source": "instagram",
    "connectedAt": "2026-01-07T10:35:00Z",
    "extractionDuration": 45000
  }
}