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.

​
Connections Response

When a user successfully connects, onSuccess receives an array of Connection objects. Users can connect multiple providers in a single session. 
// onSuccess receives Connection[]
[
  {
    grant_id: "550e8400-e29b-41d4-a716-446655440000",  // Store this!
    provider: "google",
    provider_name: "Google",
    account_identifier: "[email protected]",
    timestamp: "2024-01-15T10:30:00Z",
    operation: "creation",  // "creation" or "reauth"
    scopes: [
      "openid",
      "email",
      "profile",
      "https://www.googleapis.com/auth/calendar.readonly"
    ],
    status: "active",
    metadata: {
      // Additional provider-specific data
    }
  }
]
Important: Store each grant_id in the application database, mapped to the user. This is how API calls are made later via vault.request(method, url, { grantId }). The grant_id is generated when the end user completes the OAuth flow — it is not something the developer creates.
Store account_identifier too (e.g., "[email protected]"). When a user connects multiple accounts to the same provider (personal + work Gmail), the account_identifier lets the application show a picker or set a default account per feature.

​
Provider Filtering

Omit allowed_providers to automatically show ALL providers configured in the Developer Portal: 
app.post('/api/alter/session', async (req, res) => {
  const session = await vault.createConnectSession({
    // No allowedProviders = show all configured providers
  });

  res.json({ session_token: session.sessionToken });
});
Best Practice: Configure providers in the Developer Portal, then omit allowed_providers in application code. This keeps provider management centralized and avoids hardcoding provider lists.

​
Restrict by User Tier or Feature

Use allowed_providers to dynamically filter which providers users can access: 
// Show only premium providers to paying users
const allowed = req.user.isPremium
  ? ['google', 'github', 'sentry']  // Premium providers
  : ['google'];  // Free tier

const session = await vault.createConnectSession({
  allowedProviders: allowed,  // Dynamic filtering
});
Security: Alter automatically filters requested providers to only those configured in the Developer Portal. Users cannot access unconfigured providers even if listed in allowed_providers.

​
Smart UX Features

​
Single Provider Flow

When only one provider is available, the backend Connect UI automatically skips the selection screen and goes straight to OAuth: 
// Backend: Only Google configured or requested
allowed_providers: ['google']

// Result: Connect UI opens Google OAuth directly

​
Multiple Provider Flow

When multiple providers are available, the Connect UI shows a provider selection screen: 
// Backend: Multiple providers
allowed_providers: ['google', 'slack', 'github', 'sentry']

// Result: Connect UI shows provider selection, user picks one

​
Common Patterns

​
Validate Provider Type

await alterConnect.open({
  token: session_token,
  onSuccess: async (connections) => {
    // Check that Google was connected
    const google = connections.find(c => c.provider === 'google');
    if (!google) {
      alert('Please connect your Google account for calendar sync');
      return;
    }

    for (const conn of connections) {
      await saveConnection(conn);
    }
  }
});

​
Validate Email Domain

await alterConnect.open({
  token: session_token,
  onSuccess: async (connections) => {
    // Validate work email for all connections
    for (const conn of connections) {
      if (!conn.account_identifier.endsWith('@company.com')) {
        alert('Please use your @company.com work email');
        return;
      }
      await saveConnection(conn);
    }
  }
});

​
Handle Reauthentication

await alterConnect.open({
  token: session_token,
  onSuccess: async (connections) => {
    for (const conn of connections) {
      if (conn.operation === 'reauth') {
        console.log('Successfully reauthenticated', conn.provider);
        await updateConnection(conn);
      } else {
        console.log('New connection created', conn.provider);
        await createConnection(conn);
      }
    }
  }
});

​
Error Handling

onError: (error) => {
  if (error.code === 'session_expired') {
    // Get new session token and retry
    const newToken = await getNewSessionToken();
    alterConnect.open({ token: newToken, ... });
  }
}
Note: Session tokens expire after 10 minutes
onError: (error) => {
  if (error.code === 'invalid_token') {
    console.error('Invalid session token');
    // Check backend implementation
  }
}
Fix: Verify the backend is creating tokens correctly

​
TypeScript Support

Full TypeScript support with type definitions: 
import AlterConnect, { Connection, AlterError } from '@alter-ai/connect';

const alterConnect = AlterConnect.create({
  debug: true
});

await alterConnect.open({
  token: sessionToken,
  onSuccess: (connections: Connection[]) => {
    // TypeScript knows all properties
    for (const conn of connections) {
      const id: string = conn.grant_id;
      const provider: string = conn.provider;
      const scopes: string[] = conn.scopes;
    }
  },
  onError: (error: AlterError) => {
    const code: string = error.code;
    const message: string = error.message;
  }
});

​
Next Steps

API Reference

Complete SDK API documentation