Creating a Connection

You can create a Connection in Descope using three different methods:

1. Manually in the Console: Navigate to the Connections section of the console and select + Connection. You can then select a custom connection, or one of our preconfigured connections within the library.
2. Programmatically via APIs/SDKs: Use the CRUD APIs to create connections programmatically through the Descope Management API or SDKs.
3. From a DCR Preset Connection: Create a new connection instance from a DCR preset connection. This is useful when building an MCP gateway, or when you want to create different tenant-specific connections for an OAuth provider used with another MCP server.

There are two different types of Connections in Descope: OAuth-based and API key-based Connections.

OAuth Connections

This section covers the general set up for all OAuth-based Connections. This includes custom connections, as well as pre-configured connections from our library.

Connection Details

Within this section, you can find and configure the information regarding your connection below.

• Logo (Optional): You can upload a logo for the connection by clicking the edit button on the logo. The "Connect To" consent button within your flows for the connection will automatically utilize this logo.
• Connection Name (Required): This is the configurable name of the connection.
• Description (Optional): This is the chosen description of your connection, and it is editable.
• Connection ID (Required): This is configurable only during the creation of the connection. Once the initial configuration is complete, this field will not be editable.

Account Information

Within this section, you will define the connection settings and scopes for your connection.

Connection Settings

Here, you will configure the connection to the provider. This example shows one of the preconfigured applications (Google Contacts).

• Client ID (Required): The ID from the provider when creating your authentication account
• Client Secret (Required): The secret from the provider when creating your authentication account
• Callback Domain (Optional): The domain to use for callbacks. This will default to the configured domain within project settings.
• Callback URL for app registration (Pre-defined): To use a custom domain in your OAuth verification screen, configure a custom domain on the Project page.

Scopes

If you're using Connections with an MCP Server, it's recommended that you define the scopes you want to request from your OAuth provider in the MCP server configuration.

That way Descope can fetch the exact OAuth token needed for your MCP tool, based on whatever MCP server scopes the agent or MCP client possesses in its access token.

You can also define default scopes for your Connection, which will be included in every /authorize request to your OAuth provider.

For example, Google Contacts defaults to full access (https://www.googleapis.com/auth/contacts), but you can configure read-only access (https://www.googleapis.com/auth/contacts.readonly) instead, by configuring the default scopes for your Connection here in the console:

Additional Settings

Within the additional settings section, you can configure more details for how your connection behaves on successful consent, authorization, and token endpoint configuration.

• Redirect URL (Optional): The default redirect URL after a successful connection. This value will be overridden when using flows or specifying the redirect URL in the API/SDK call.
• Authorization Endpoint (Required): The endpoint to request authorization from the user.
• Token Endpoint (Required): The endpoint to exchange the authorization code for an access token.

Once created, you can read how you can connect to your OAuth provider, and fetch the OAuth tokens with our SDKs.

API Key Connections

In addition to storing OAuth tokens, Descope can also store static API keys with API Key-based Connections.

There are a few Connection templates that use API keys, such as Jenkins and OpenAI, but you can also create your own Custom API key Connection as well.

Connection Details

Within this section, you can find and configure the information regarding your connection below.

• Logo (Optional): You can upload a logo for the connection by clicking the edit button on the logo. The "Connect To" consent button within your flows for the connection will automatically utilize this logo.
• Connection Name (Required): This is the configurable name of the connection.
• Description (Optional): This is the chosen description of your connection, and it is editable.
• Connection ID (Required): This is configurable only during the creation of the connection. Once the initial configuration is complete, this field will not be editable.

API key based connections don't have any additional settings besides the details above. Once created, you can read how you can upload static tokens (API keys) to your connection, and fetch them with our SDKs.

Managing Connections

You can create, update, delete, and load connections programmatically using a Descope SDK directly via the REST API.

Create a Connection

// Create a connection
const { id } = await descopeClient.management.outboundApplication.createApplication({
  name: 'my new connection',
  description: 'my desc',
  // ...other fields (see [Connection Schema](#connection-schema) below)
});

Update a Connection

// Update a connection (overrides all fields)
await descopeClient.management.outboundApplication.updateApplication({
  id: 'my-connection-id',
  name: 'my updated connection',
  // ...other fields (see [Connection Schema](#connection-schema))
});

Delete a Connection

// Delete a connection by id
await descopeClient.management.outboundApplication.deleteApplication('my-connection-id');

Load a Connection

// Load a connection by id
const connection = await descopeClient.management.outboundApplication.loadApplication('my-connection-id');

Load All Connections

// Load all connections
const connectionsRes = await descopeClient.management.outboundApplication.loadAllApplications();
connectionsRes.data.forEach((connection) => {
  // do something
});

Connection Schema

When creating or updating a connection, you can configure the following fields:

Connection Fields

URL Parameter Structure

The authorizationUrlParams and tokenUrlParams fields accept an array of URL parameter objects with the following structure:

Here's an example of a complete connection object with all available fields:

const connection = {
  name: 'Google Contacts',
  description: 'Access Google Contacts API',
  logo: 'https://example.com/logo.png',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
  tokenUrl: 'https://oauth2.googleapis.com/token',
  defaultScopes: ['https://www.googleapis.com/auth/contacts.readonly'],
  defaultRedirectUrl: 'https://app.example.com/callback',
  callbackDomain: 'app.example.com',
  pkce: true,
  accessType: 'offline',
  prompt: ['consent']
};

For more information on how to store tokens and connect to your Connection, see the Storing Connection Tokens documentation.

For more information on how to fetch these tokens see this doc.