Example Tools using Outbound Apps

Here are examples of how backend services can use Descope Outbound Apps to retrieve user-specific tokens for third-party platforms like Salesforce, HubSpot, and Google Calendar.

Each example assumes the user has already connected via the outbound app connect flow, either using the Frontend SDKs or Descope Flows.

Fetching Outbound App Tokens

To use tokens from your backend, you'll need to fetch them using the Descope Management API. Below are examples in different languages:

Node.js / JavaScript

// Node.js example using fetch API
async function getOutboundToken(appId, userId, scopes = []) {
  const projectId = process.env.DESCOPE_PROJECT_ID;
  const managementKey = process.env.DESCOPE_MANAGEMENT_KEY;
  
  const response = await fetch('https://api.descope.com/v1/mgmt/outbound/app/user/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${projectId}:${managementKey}`
    },
    body: JSON.stringify({
      appId,
      userId,
      scopes,
      options: {
        withRefreshToken: false,
        forceRefresh: false
      }
    })
  });
  
  if (!response.ok) {
    throw new Error(`Failed to fetch token: ${response.status} ${response.statusText}`);
  }
  
  const data = await response.json();
  return data.token;
}

Python

import requests
 
def get_outbound_token(app_id, user_id, scopes=None):
    project_id = "YOUR_PROJECT_ID"
    management_key = "YOUR_MANAGEMENT_KEY"
    
    url = "https://api.descope.com/v1/mgmt/outbound/app/user/token"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {project_id}:{management_key}"
    }
    
    payload = {
        "appId": app_id,
        "userId": user_id,
        "scopes": scopes or [],
        "options": {
            "withRefreshToken": False,
            "forceRefresh": False
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code != 200:
        raise Exception(f"Failed to fetch token: {response.status_code} {response.text}")
    
    data = response.json()
    return data["token"]

🔗 Salesforce Opportunities Tool

Use Descope Outbound Apps to fetch Salesforce access tokens, then query opportunities from the Salesforce API.

// Fetch the token from Descope Management API
const token = await getOutboundToken("salesforce", "user-123", ["full"]);
const accessToken = token.accessToken;
 
const instanceUrl = process.env.SALESFORCE_INSTANCE_URL;
const query = `SELECT Id, Name, StageName, CloseDate FROM Opportunity LIMIT 5`;
const endpoint = `${instanceUrl}/services/data/v57.0/query/?q=${encodeURIComponent(query)}`;
 
const response = await fetch(endpoint, {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
const data = await response.json();

📅 Google Calendar Events Tool

Fetch a user's calendar events with Descope-managed tokens:

// Fetch the token from Descope Management API
const token = await getOutboundToken(
  "google-calendar", 
  "<Descope User ID>", 
  ["https://www.googleapis.com/auth/calendar"]
);
const accessToken = token.accessToken;
 
const now = new Date().toISOString();
const url = `https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=${now}&maxResults=5&orderBy=startTime&singleEvents=true`;
 
const response = await fetch(url, {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
const events = await response.json();

📇 HubSpot Contacts Tool (Python Example)

Use the Outbound App token to get CRM contact records from HubSpot:

# Fetch the token from Descope Management API
token = get_outbound_token("hubspot", "user-123", ["contacts"])
access_token = token["accessToken"]
 
import requests
 
url = "https://api.hubapi.com/crm/v3/objects/contacts?limit=10"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}
 
response = requests.get(url, headers=headers)
contacts = response.json()

Important Notes

Store your Management Key securely - it has admin permissions to your Descope project
Use environment variables to manage your Project ID and Management Key
Token requests should only occur server-side, never in client code
Set appropriate scopes when requesting tokens for better security

Coming soon: More examples for platforms like Slack, Notion, Zoom, and GitHub!

Was this helpful?

On this page