Fetching Connection Tokens

import requests
from descope_mcp import get_connection_token

def get_contacts(user_id, mcp_access_token):
    # Fetch the Google connection token; passing the MCP access token enforces policies
    token = get_connection_token(
        user_id=user_id,
        app_id="google-contacts",
        access_token=mcp_access_token,
    )

    # Call the Google People API with the fresh, scoped token
    response = requests.get(
        "https://people.googleapis.com/v1/people/me/connections",
        headers={"Authorization": f"Bearer {token}"},
        params={"personFields": "names,emailAddresses", "pageSize": 100},
    )
    response.raise_for_status()
    connections = response.json().get("connections", [])
    return {
        "contacts": [
            {
                "name": c.get("names", [{}])[0].get("displayName", ""),
                "email": c.get("emailAddresses", [{}])[0].get("value", ""),
            }
            for c in connections
        ]
    }

import { defineTool } from '@descope/mcp-express';
import { z } from 'zod';

// The SDK validates the incoming token; extra.getOutboundToken fetches from Connections
const getContacts = defineTool({
  name: 'get_contacts',
  description: "Fetch the user's Google contacts",
  input: {},
  handler: async (_args, extra) => {
    const token = await extra.getOutboundToken('google-contacts');

    const res = await fetch(
      'https://people.googleapis.com/v1/people/me/connections?personFields=names,emailAddresses&pageSize=100',
      { headers: { Authorization: `Bearer ${token}` } },
    );
    if (!res.ok) throw new Error(`Google API error: ${res.status}`);
    const { connections = [] } = await res.json();

    const contacts = connections.map((c) => ({
      name: c.names?.[0]?.displayName ?? '',
      email: c.emailAddresses?.[0]?.value ?? '',
    }));
    return { content: [{ type: 'text', text: JSON.stringify({ contacts }) }] };
  },
});

from descope_agent_auth import AgentAuthClient, AccessTokenProvider
from descope_agent_auth.errors import ConnectionAuthorizationRequired

client = AgentAuthClient(
    project_id="YOUR_PROJECT_ID",
    credential=AccessTokenProvider(access_token=user_jwt),  # the JWT from your app's login
)

try:
    google = client.connections.get_token(connection="google-contacts", identifier=user_id)
    use(google.access_token)              # a fresh, scoped Google token
except ConnectionAuthorizationRequired as e:
    redirect_user_to(e.connect_url)       # the user hasn't linked Google yet

import { AgentAuthClient, AccessTokenProvider, ConnectionAuthorizationRequired } from '@descope/agent-auth';

const client = new AgentAuthClient({
  projectId: 'YOUR_PROJECT_ID',
  credential: new AccessTokenProvider({ accessToken: userJwt }), // the JWT from your app's login
});

try {
  const google = await client.connections.getToken({ connection: 'google-contacts', identifier: userId });
  use(google.accessToken);                // a fresh, scoped Google token
} catch (e) {
  if (e instanceof ConnectionAuthorizationRequired) {
    redirectUserTo(e.connectUrl);         // the user hasn't linked Google yet
  } else {
    throw e;
  }
}

// Fetch latest user token
const latestUserToken = await descopeClient.management.outboundApplication.fetchToken(
  'my-app-id',
  'user-id',
  'tenant-id', // optional
  { forceRefresh: false, withRefreshToken: false } // optional
);

# Fetch latest user token
latest_user_token = descope_client.mgmt.outbound_application.fetch_token(
    app_id='my-app-id',
    user_id='user-id',
    tenant_id='tenant-id',  # optional
    options={
        'forceRefresh': False,  # optional
        'withRefreshToken': False  # optional
    }
)

import com.descope.DescopeClient;
import com.descope.sdk.mgmt.OutboundAppsService;

// Initialize the Descope client
DescopeClient descopeClient = new DescopeClient("YOUR_PROJECT_ID", "YOUR_MANAGEMENT_KEY");
OutboundAppsService outboundAppsService = descopeClient.getManagementServices().getOutboundAppsService();

// Fetch latest token
FetchOutboundAppUserTokenRequest request = new FetchOutboundAppUserTokenRequest();
request.setAppId("google-contacts");
request.setUserId("user-123");
request.setTenantId("tenant-id"); // optional

FetchOutboundAppUserTokenResponse response = outboundAppsService.fetchOutboundAppUserTokenLatest(request);
String accessToken = response.getToken().getAccessToken();

// Note: Go SDK only supports fetching tokens by specific scopes, not latest tokens
// See "Fetch Token with Specific Scopes" section below

curl -X POST "https://api.descope.com/v1/mgmt/outbound/app/user/token/latest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY> or <PROJECT_ID:ACCESS_TOKEN>" \
  -d '{
  "appId": "google-contacts",
  "userId": "xxxxx",
  "tenantId": "optional-tenant-id",
  "options": {
    "withRefreshToken": false,
    "forceRefresh": false
  }
}'

// Fetch user token with specific scopes
const userToken = await descopeClient.management.outboundApplication.fetchTokenByScopes(
  'my-app-id',
  'user-id',
  ['read', 'write'],
  { withRefreshToken: false }, // optional
  'tenant-id' // optional
);

# Fetch user token with specific scopes
user_token = descope_client.mgmt.outbound_application.fetch_token_by_scopes(
    app_id='my-app-id',
    user_id='user-id',
    scopes=['read', 'write'],
    options={
        'withRefreshToken': False  # optional
    },
    tenant_id='tenant-id'  # optional
)

import com.descope.DescopeClient;
import com.descope.sdk.mgmt.OutboundAppsService;

// Initialize the Descope client
DescopeClient descopeClient = new DescopeClient("YOUR_PROJECT_ID", "YOUR_MANAGEMENT_KEY");
OutboundAppsService outboundAppsService = descopeClient.getManagementServices().getOutboundAppsService();

// Fetch token with specific scopes
FetchOutboundAppUserTokenRequest request = new FetchOutboundAppUserTokenRequest();
request.setAppId("google-contacts");
request.setUserId("user-123");
request.setScopes(Arrays.asList("https://www.googleapis.com/auth/contacts.readonly"));
request.setTenantId("tenant-id"); // optional

FetchOutboundAppUserTokenResponse response = outboundAppsService.fetchOutboundAppUserToken(request);
String accessToken = response.getToken().getAccessToken();

// Fetch user token with specific scopes
request := &descope.FetchOutboundAppUserTokenRequest{
    AppID:    "my-app-id",
    UserID:   "user-id",
    Scopes:   []string{"read", "write"},
    TenantID: "tenant-id", // optional
    Options: &descope.OutboundAppUserTokenOptions{
        WithRefreshToken: false, // optional
    },
}

token, err := descopeClient.Management.OutboundApplication().FetchUserToken(ctx, request)
if err != nil {
    // Handle error
}
accessToken := token.AccessToken

curl -X POST "https://api.descope.com/v1/mgmt/outbound/app/user/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY> or <PROJECT_ID:ACCESS_TOKEN>" \
  -d '{
  "appId": "google-contacts",
  "userId": "xxxxx",
  "tenantId": "optional-tenant-id",
  "scopes": [
    "https://www.googleapis.com/auth/contacts.readonly"
  ],
  "options": {
    "withRefreshToken": false,
    "forceRefresh": false
  }
}'

// Fetch latest tenant token
const latestTenantToken = await descopeClient.management.outboundApplication.fetchTenantToken(
  'my-app-id',
  'tenant-id',
  { forceRefresh: false } // optional
);

# Fetch latest tenant token
latest_tenant_token = descope_client.mgmt.outbound_application.fetch_tenant_token(
    app_id='my-app-id',
    tenant_id='tenant-id',
    options={
        'forceRefresh': False,  # optional
        'withRefreshToken': False  # optional
    }
)

import com.descope.DescopeClient;
import com.descope.sdk.mgmt.OutboundAppsService;

// Initialize the Descope client
DescopeClient descopeClient = new DescopeClient("YOUR_PROJECT_ID", "YOUR_MANAGEMENT_KEY");
OutboundAppsService outboundAppsService = descopeClient.getManagementServices().getOutboundAppsService();

// Fetch latest tenant token
FetchOutboundAppTenantTokenRequest request = new FetchOutboundAppTenantTokenRequest();
request.setAppId("google-contacts");
request.setTenantId("tenant-123");

FetchOutboundAppTenantTokenResponse response = outboundAppsService.fetchOutboundAppTenantTokenLatest(request);
String accessToken = response.getToken().getAccessToken();

// Note: Go SDK does not currently support tenant-level token fetching
// Use the REST API directly for tenant-level operations

curl -X POST "https://api.descope.com/v1/mgmt/outbound/app/tenant/token/latest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY> or <PROJECT_ID:ACCESS_TOKEN>" \
  -d '{
  "appId": "google-contacts",
  "tenantId": "tenant-123",
  "options": {
    "withRefreshToken": false,
    "forceRefresh": false
  }
}'

// Fetch tenant token with specific scopes
const tenantToken = await descopeClient.management.outboundApplication.fetchTenantTokenByScopes(
  'my-app-id',
  'tenant-id',
  ['read', 'write'],
  { withRefreshToken: false } // optional
);

# Fetch tenant token with specific scopes
tenant_token = descope_client.mgmt.outbound_application.fetch_tenant_token_by_scopes(
    app_id='my-app-id',
    tenant_id='tenant-id',
    scopes=['read', 'write'],
    options={
        'withRefreshToken': False  # optional
    }
)

import com.descope.DescopeClient;
import com.descope.sdk.mgmt.OutboundAppsService;

// Initialize the Descope client
DescopeClient descopeClient = new DescopeClient("YOUR_PROJECT_ID", "YOUR_MANAGEMENT_KEY");
OutboundAppsService outboundAppsService = descopeClient.getManagementServices().getOutboundAppsService();

// Fetch tenant token with specific scopes
FetchOutboundAppTenantTokenRequest request = new FetchOutboundAppTenantTokenRequest();
request.setAppId("google-contacts");
request.setTenantId("tenant-123");
request.setScopes(Arrays.asList("https://www.googleapis.com/auth/contacts.readonly"));

FetchOutboundAppTenantTokenResponse response = outboundAppsService.fetchOutboundAppTenantToken(request);
String accessToken = response.getToken().getAccessToken();

// Note: Go SDK does not currently support tenant-level token fetching
// Use the REST API directly for tenant-level operations

curl -X POST "https://api.descope.com/v1/mgmt/outbound/app/tenant/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY> or <PROJECT_ID:ACCESS_TOKEN>" \
  -d '{
  "appId": "google-contacts",
  "tenantId": "tenant-123",
  "scopes": [
    "https://www.googleapis.com/auth/contacts.readonly"
  ],
  "options": {
    "withRefreshToken": false,
    "forceRefresh": false
  }
}'

// Fetch a connection token with proper error handling.
async function fetchConnectionToken(appId, userId, scopes = null) {
  const url = scopes
    ? "https://api.descope.com/v1/mgmt/outbound/app/user/token"          // specific scopes
    : "https://api.descope.com/v1/mgmt/outbound/app/user/token/latest";  // latest token
  const body = scopes ? { appId, userId, scopes } : { appId, userId };

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${PROJECT_ID}:${MANAGEMENT_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      if (response.status === 404) {
        // Token not found: either never existed or was cleared recently
        console.log("Token not found. The user may not have connected to this connection, or the token may have been cleared.");
      } else if (response.status === 500) {
        // Server error: issue with HTTP request method or JSON payload
        console.log("Server error. Check your request method (should be POST) and ensure your JSON payload is properly formatted.");
      } else {
        console.log(`HTTP error occurred: ${response.status}`);
      }
      return null;
    }
    return await response.json();
  } catch (e) {
    console.log(`Request failed: ${e.message}`);
    return null;
  }
}

// Make a request to a third-party API with proper error handling.
async function makeApiRequest(accessToken, url, params = {}) {
  const query = new URLSearchParams(params).toString();

  try {
    const response = await fetch(query ? `${url}?${query}` : url, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });

    if (!response.ok) {
      if (response.status === 401) console.log("Access token may be invalid or expired");
      else if (response.status === 403) console.log("Insufficient permissions for this request");
      else console.log(`HTTP error occurred: ${response.status}`);
      return null;
    }
    return await response.json();
  } catch (e) {
    console.log(`Request failed: ${e.message}`);
    return null;
  }
}

import requests
from requests.exceptions import RequestException

def fetch_connection_token(app_id, user_id, scopes=None):
    """Fetch a connection token with proper error handling."""
    headers = {"Authorization": f"Bearer {PROJECT_ID}:{MANAGEMENT_KEY}"}
    
    try:
        if scopes:
            # Use specific scopes endpoint
            url = "https://api.descope.com/v1/mgmt/outbound/app/user/token"
            data = {"appId": app_id, "userId": user_id, "scopes": scopes}
        else:
            # Use latest token endpoint
            url = "https://api.descope.com/v1/mgmt/outbound/app/user/token/latest"
            data = {"appId": app_id, "userId": user_id}
        
        response = requests.post(url, headers=headers, json=data, timeout=30)
        response.raise_for_status()
        return response.json()
        
    except requests.exceptions.HTTPError as e:
        if response.status_code == 404:
            # Token not found - either never existed or was cleared recently
            print("Token not found. The user may not have connected to this connection, "
                  "or the token may have been cleared.")
            return None
        elif response.status_code == 500:
            # Server error - issue with HTTP request method or JSON payload
            print("Server error. Check your request method (should be POST) "
                  "and ensure your JSON payload is properly formatted.")
            return None
        else:
            print(f"HTTP error occurred: {e}")
            return None
    except requests.exceptions.Timeout:
        print("Request timed out")
        return None
    except RequestException as e:
        print(f"Request failed: {e}")
        return None

def make_api_request(access_token, url, params=None):
    """Make a request to a third-party API with proper error handling."""
    headers = {"Authorization": f"Bearer {access_token}"}
    
    try:
        response = requests.get(url, headers=headers, params=params, timeout=30)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if response.status_code == 401:
            print("Access token may be invalid or expired")
        elif response.status_code == 403:
            print("Insufficient permissions for this request")
        else:
            print(f"HTTP error occurred: {e}")
        return None
    except requests.exceptions.Timeout:
        print("Request timed out")
        return None
    except RequestException as e:
        print(f"Request failed: {e}")
        return None

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"time"
)

var httpClient = &http.Client{Timeout: 30 * time.Second}

// fetchConnectionToken fetches a connection token with proper error handling.
func fetchConnectionToken(appID, userID string, scopes []string) (map[string]interface{}, error) {
	endpoint := "https://api.descope.com/v1/mgmt/outbound/app/user/token/latest" // latest token
	payload := map[string]interface{}{"appId": appID, "userId": userID}
	if len(scopes) > 0 {
		endpoint = "https://api.descope.com/v1/mgmt/outbound/app/user/token" // specific scopes
		payload["scopes"] = scopes
	}

	body, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(body))
	req.Header.Set("Authorization", fmt.Sprintf("Bearer %s:%s", projectID, managementKey))
	req.Header.Set("Content-Type", "application/json")

	resp, err := httpClient.Do(req)
	if err != nil {
		fmt.Println("Request failed:", err)
		return nil, err
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case http.StatusOK:
		var result map[string]interface{}
		json.NewDecoder(resp.Body).Decode(&result)
		return result, nil
	case http.StatusNotFound:
		// Token not found: either never existed or was cleared recently
		fmt.Println("Token not found. The user may not have connected to this connection, or the token may have been cleared.")
	case http.StatusInternalServerError:
		// Server error: issue with HTTP request method or JSON payload
		fmt.Println("Server error. Check your request method (should be POST) and ensure your JSON payload is properly formatted.")
	default:
		fmt.Printf("HTTP error occurred: %d\n", resp.StatusCode)
	}
	return nil, nil
}

// makeAPIRequest calls a third-party API with proper error handling.
func makeAPIRequest(accessToken, endpoint string, params map[string]string) (map[string]interface{}, error) {
	q := url.Values{}
	for k, v := range params {
		q.Set(k, v)
	}
	full := endpoint
	if len(q) > 0 {
		full = endpoint + "?" + q.Encode()
	}

	req, _ := http.NewRequest("GET", full, nil)
	req.Header.Set("Authorization", "Bearer "+accessToken)

	resp, err := httpClient.Do(req)
	if err != nil {
		fmt.Println("Request failed:", err)
		return nil, err
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case http.StatusOK:
		var result map[string]interface{}
		json.NewDecoder(resp.Body).Decode(&result)
		return result, nil
	case http.StatusUnauthorized:
		fmt.Println("Access token may be invalid or expired")
	case http.StatusForbidden:
		fmt.Println("Insufficient permissions for this request")
	default:
		fmt.Printf("HTTP error occurred: %d\n", resp.StatusCode)
	}
	return nil, nil
}