Connect to Outbound Apps

Once you've created an Outbound App, you can start connecting your users to third-party services through Descope Outbound Apps. You can choose between:

1. Using Frontend SDKs - For custom UI integrations in your application
2. Using Descope Flows - For low-code integration with pre-built UI components
3. Using APIs - For non-JavaScript platforms

Connecting with Frontend SDKs

Install the appropriate Descope SDK for your application:

# For vanilla JavaScript applications
npm install @descope/web-js-sdk
 
# For React applications
npm install @descope/react-sdk
 
# For Next.js applications
npm install @descope/nextjs-sdk

Using the connect() Function

The outbound.connect() function initiates a redirect to the authorization endpoint of your Outbound App provider, handling all OAuth redirect mechanics for you.

Parameters

• providerId (required): The ID of the Outbound App you've configured in Descope
• options (optional): Configuration for the connection:
  • redirectURL: Custom URL to redirect after authentication
  • scopes: Array of specific scopes to request
• token (optional): Authentication token (if not already set in the SDK)

Code Examples

import { useDescope } from '@descope/react-sdk';
 
function ConnectButton() {
  const { sdk } = useDescope();
  
  const handleConnect = async () => {
    try {
      await sdk.outbound.connect('<outbound-app-id>', {
        redirectURL: 'https://app.example.com/post-connection',
      });
    } catch (error) {
      console.error('Error connecting to Google:', error);
    }
  };
  
  return (
    <button onClick={handleConnect}>
      Connect to Outbound App
    </button>
  );
}
 
export default ConnectButton;

Customizing the Connection

You can provide additional options to the connect function to customize the authorization request:

// Works with any of the SDKs
await sdk.outbound.connect(
  'google-calendar',
  {
    // Override the redirect URL (must be registered in your Outbound App)
    redirectURL: 'https://your-app.com/post-connection',
    
    // Specify particular scopes (overrides the default scopes)
    scopes: [
      'https://www.googleapis.com/auth/calendar', 
      'https://www.googleapis.com/auth/contacts.readonly'
    ]
  }
);

Handling the Redirect

After successful authentication, the provider redirects back to your application. Descope will automatically handle the redirect back to where you set your redirect URL shown above.

At this point, Descope will now be managing the tokens for this user. You can use the Management API to retrieve the tokens for backend operations.

Connecting with Descope Flows

For a low-code approach with pre-built UI components, you can use Descope Flows to manage the connection process.

Descope Flows provide:

• Pre-built UI components for connection buttons
• Managed redirect handling
• Easy customization options

Flow Components for Outbound Apps

There are two main components:

1. Outbound App Button - A button component that initiates the connection
2. Outbound App Connect Action - The action that processes the connection request

Implementation Options

You can implement outbound app connections in flows in two ways:

Option 1: Using the Outbound App Button

Place an Outbound App button on your flow screen that users can click to initiate the connection. The button can be customized with text and styling options, and it automatically displays the outbound app's logo.

Option 2: Using the Connect Action Directly

If you want to use your own UI elements, you can trigger the Outbound App Connect action directly from your application. Set a default outbound app in the action's configuration to bypass the need for Descope's UI components.

Connecting with APIs

For non-JavaScript platforms, you can use this API directly to initiate connections:

POST https://api.descope.com/v1/outbound/oauth/connect
Authorization: Bearer <project_id>:<refreshJWT>
Content-Type: application/json
 
{
  "appId": "<outbound-app-id>",
  "options": {
    "redirectUrl": "https://your-redirect-url.com",
    "scopes": ["scope1", "scope2"]  // Optional
  }
}

The redirectUrl parameter in the options object is required and specifies where the user will be redirected after the authorization process completes. The scopes parameter is optional and allows you to request specific permissions different from the default scopes configured in your Outbound App.

After calling this endpoint, the server will respond with a redirect URL that you should redirect your user to in order to begin the OAuth consent flow.

Next Steps

After a user connects to an outbound app, you can:

1. Use the Management API to retrieve tokens for backend operations
2. Connect to multiple providers for the same user

For working code examples, see our Outbound Apps Examples.