Skip to main content

​
Overview

The Pipes API enables you to retrieve access tokens for third-party data integration providers that your users have connected through WorkOS. This allows you to access your users’ data from external services like CRM systems, project management tools, and other SaaS applications.
Pipes is part of WorkOS’s data integration platform, which provides a unified API for accessing user data across multiple third-party providers.

​
Methods

​
getAccessToken

Retrieves an access token for a specific data integration provider.
​
options
GetAccessTokenOptions & { provider: string }
required
Options for retrieving the access token
​
GetAccessTokenResponse
object
The access token response, which can be either a success or failure

​
Example - Active Connection

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const result = await workos.pipes.getAccessToken({
  provider: 'salesforce',
  userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
});

if (result.active) {
  const { accessToken, scopes, expiresAt } = result.accessToken;
  
  console.log('Access token:', accessToken);
  console.log('Scopes:', scopes);
  console.log('Expires at:', expiresAt);
  
  // Use the access token to call the provider's API
  const response = await fetch('https://api.salesforce.com/services/data/v58.0/sobjects', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  });
} else {
  console.log('Connection not active:', result.error);
  
  if (result.error === 'not_installed') {
    // Prompt user to connect the provider
  } else if (result.error === 'needs_reauthorization') {
    // Prompt user to reauthorize the connection
  }
}

​
Response - Success

{
  "active": true,
  "accessToken": {
    "object": "access_token",
    "accessToken": "ya29.a0AfH6SMBx...",
    "expiresAt": "2024-03-02T16:30:00Z",
    "scopes": [
      "https://www.googleapis.com/auth/userinfo.email",
      "https://www.googleapis.com/auth/userinfo.profile"
    ],
    "missingScopes": []
  }
}

​
Response - Not Installed

{
  "active": false,
  "error": "not_installed"
}

​
Response - Needs Reauthorization

{
  "active": false,
  "error": "needs_reauthorization"
}

​
Working with Different Providers

​
Example - Slack Integration

const result = await workos.pipes.getAccessToken({
  provider: 'slack',
  userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
});

if (result.active) {
  // Post a message to Slack
  await fetch('https://slack.com/api/chat.postMessage', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${result.accessToken.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      channel: '#general',
      text: 'Hello from WorkOS Pipes!',
    }),
  });
}

​
Example - HubSpot CRM

const result = await workos.pipes.getAccessToken({
  provider: 'hubspot',
  userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
});

if (result.active) {
  // Fetch contacts from HubSpot
  const response = await fetch('https://api.hubapi.com/crm/v3/objects/contacts', {
    headers: {
      'Authorization': `Bearer ${result.accessToken.accessToken}`,
    },
  });
  
  const contacts = await response.json();
  console.log('HubSpot contacts:', contacts);
}

​
Error Handling

try {
  const result = await workos.pipes.getAccessToken({
    provider: 'salesforce',
    userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
  });
  
  if (!result.active) {
    switch (result.error) {
      case 'not_installed':
        // Redirect user to connection flow
        return {
          message: 'Please connect your Salesforce account',
          connectUrl: '/integrations/salesforce/connect',
        };
      
      case 'needs_reauthorization':
        // Prompt user to reauthorize
        return {
          message: 'Your Salesforce connection needs to be reauthorized',
          reauthorizeUrl: '/integrations/salesforce/reauthorize',
        };
    }
  }
  
  // Use the access token
  const { accessToken } = result.accessToken;
  // ...
} catch (error) {
  console.error('Failed to get access token:', error);
}

​
Token Expiration

Access tokens may expire. Check the expiresAt field and handle token refresh appropriately. WorkOS automatically handles token refresh for OAuth providers that support it.
const result = await workos.pipes.getAccessToken({
  provider: 'google',
  userId: 'user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
});

if (result.active) {
  const { accessToken, expiresAt } = result.accessToken;
  
  if (expiresAt && new Date(expiresAt) < new Date()) {
    console.log('Token has expired, WorkOS will refresh it automatically');
  }
  
  // Token is valid or will be automatically refreshed
  // Use it to call the provider's API
}

​
Supported Providers

Pipes supports a wide range of data integration providers, including:

Salesforce

CRM and customer data

HubSpot

Marketing and CRM platform

Slack

Team communication

Google Workspace

Email, calendar, and docs

Microsoft 365

Office applications and data

Jira

Project and issue tracking
For a complete list of supported providers and their required scopes, refer to the WorkOS Pipes documentation.

​
Use Cases

Sync customer data between your application and CRM systems like Salesforce or HubSpot.
Access and manage user calendars from Google Calendar or Microsoft Outlook.
Integrate with Slack, Microsoft Teams, or other collaboration tools.
Access files and documents from Google Drive, Dropbox, or SharePoint.
Integrate with Jira, Asana, or Monday.com for project tracking.

​
Best Practices

Always check the active status before attempting to use an access token. Handle both not_installed and needs_reauthorization errors gracefully by prompting users to reconnect.
Never expose access tokens to client-side code. Always retrieve and use tokens server-side to protect user data.
Check the missingScopes array to identify permissions that were requested but not granted. You may need to prompt users to reauthorize with additional scopes.

User Management

Manage users who connect integrations

Organizations

Organize integrations by organization

Webhooks

Receive notifications when connections change

Audit Logs

Track integration access and usage

Build docs developers (and LLMs) love

Get started for freeTalk to us