Skip to main content
const session = await airstore.oauth.createSession({
  integrationType: 'gmail',
  workspaceId: 'ws_abc123',
})
// Redirect the user to session.authorize_url
Integrations connect external services (Gmail, GitHub, Google Drive, etc.) to a workspace. Once connected, their data becomes available in the virtual filesystem through smart folders. The SDK supports two ways to connect integrations:
  1. OAuth flow — Redirect the user to authorize access, then poll for completion. Best for interactive setups.
  2. Direct credentials — Pass existing OAuth tokens or API keys directly. Best for backend automation where you already have credentials.

​
OAuth flow

This is the most common approach. You create a session, send the user to the authorization URL, and poll until they complete it.

​
Step 1: Create an OAuth session

import Airstore from '@airstore/sdk'

const airstore = new Airstore()

const session = await airstore.oauth.createSession({
  integrationType: 'gmail',
  workspaceId: 'ws_abc123',
})

console.log(session.authorize_url)
// "https://accounts.google.com/o/oauth2/v2/auth?..."
Redirect the user to session.authorize_url in their browser. After they approve access, Airstore handles the callback and stores the credentials.

​
Step 2: Poll for completion

const result = await airstore.oauth.poll(session.session_id)

console.log(result.status)        // "complete"
console.log(result.connection_id) // "conn_xyz789"
poll() checks the session status every 2 seconds (configurable) and resolves when the user completes or denies authorization. It throws if the session times out or errors. 
// Custom polling options
const result = await airstore.oauth.poll(session.session_id, {
  timeout: 120_000,  // 2 minutes instead of default 5
  interval: 1_000,   // Check every second
})

​
Step 3: Verify the connection

const connections = await airstore.connections.list('ws_abc123')
const gmail = connections.find(c => c.integration_type === 'gmail')
console.log(gmail?.external_id)

​
Direct credentials

If you already have OAuth tokens or an API key, skip the redirect flow entirely: 
// OAuth-based integration (Gmail, GitHub, etc.)
await airstore.connections.create('ws_abc123', {
  integrationType: 'github',
  accessToken: 'ghp_xxxxxxxxxxxx',
})

// API key integration (PostHog, etc.)
await airstore.connections.create('ws_abc123', {
  integrationType: 'posthog',
  apiKey: 'phx_xxxxxxxxxxxx',
})
This is useful when your backend already manages OAuth tokens for users and you want to pass them through to Airstore without a second authorization prompt.

​
Supported integrations

IntegrationTypeAuthentication
GmailgmailOAuth
Google DrivegdriveOAuth
GitHubgithubOAuth or token
NotionnotionOAuth or token
LinearlinearOAuth
SlackslackOAuth
PostHogposthogAPI key

​
Remove a connection

await airstore.connections.del('ws_abc123', 'conn_xyz789')

​
Next steps

Create smart folders

Turn your connected data into browsable folders.

OAuth reference

Full method reference for client.oauth.