Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

Get started with the Alter Connect frontend SDK to add OAuth popup flows to a single-page application.

​
Installation

npm install @alter-ai/connect
This frontend SDK is optional. The Alter Connect UI is a hosted page. The backend can create a session and redirect users to the connect_url directly without any frontend SDK. This SDK is for SPAs (React, Vue, etc.) that want a popup overlay with real-time onSuccess/onError callbacks. See the Quickstart for all three ways to trigger the OAuth flow.
OAuth grants only. For Managed Secrets (API keys and service tokens), use the Developer Portal instead.

​
Overview

The SDK follows a secure three-step process:
1

Backend creates session

The backend uses the API key to create a session token (no user_id or grant_id needed)
2

Frontend opens Connect UI

SDK opens the OAuth flow using the session token
3

User completes OAuth

User logs into their account (e.g., Google), authorizes access, and the onSuccess callback returns a grant_id (UUID) for each connected account

​
Session Tokens

Session tokens are temporary credentials created by the backend. They allow Alter Connect to work without exposing API keys in frontend code.

​
Complete Example

​
Step 1: Backend Endpoint

Create a backend endpoint to generate session tokens: 
const { AlterVault } = require('@alter-ai/alter-sdk');

const vault = new AlterVault({
  apiKey: process.env.ALTER_API_KEY,  // Never expose this!
  caller: 'my-express-app',
});

app.post('/api/alter/session', async (req, res) => {
  const session = await vault.createConnectSession({
    allowedProviders: ['google', 'slack', 'github'],
  });

  res.json({ session_token: session.sessionToken });
});

​
Step 2: Frontend Integration

Use the SDK in the frontend to open the Connect UI: 
import AlterConnect from '@alter-ai/connect';

// Initialize SDK
const alterConnect = AlterConnect.create();

// Handle connect button click
async function connectAccount() {
  // Get session token from YOUR backend
  const response = await fetch('/api/alter/session', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${userToken}`
    }
  });
  const { session_token } = await response.json();

  // Open Connect UI
  await alterConnect.open({
    token: session_token,
    onSuccess: (connections) => {
      console.log('Connected!', connections);
      // Save each grant_id to your database
      for (const conn of connections) {
        saveConnection(conn);
      }
    },
    onError: (error) => {
      console.error('Connection failed:', error);
    },
    onExit: () => {
      console.log('User closed the popup');
    }
  });
}

​
Next Steps

SDK Overview

Connection responses, provider filtering, patterns, and error handling

API Reference

Complete SDK API documentation