Creating a Connection

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

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.
Programmatically via APIs/SDKs: Use the CRUD APIs to create connections programmatically through the Descope Management API or SDKs.
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.

Creating an connection in Descope

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

Note

The connection ID cannot be shared with any other connection or outbound app.

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.

Configuring an oauth connection's details in Descope

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.

Note

Most OAuth providers will require you to add the callback URL on this page to your OAuth application's allowed authorized callback URL list.

Configuring an outbound app's connection settings in Descope

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:

Configuring an outbound app's scopes in Descope

Note

You must also configure the same scopes in your OAuth provider's application settings (e.g., Google Cloud Console) for them to be available.

Configuring additional scopes on a Google Oauth application to be used with outbound apps in Descope

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.

Note

When using a predefined connection from the connections library, the authorization and token endpoints are prepopulated.

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.

Configuring an outbound app's additional settings in Descope

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

API Key Connections

This is ideal for integrating with external services that do not support OAuth, and use static tokens instead for authentication.

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

Note

The connection ID cannot be shared with any other connection.

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.

Configuring an api key connection's details in Descope

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)
});

# Create a connection
response = descope_client.mgmt.outbound_application.create_application(
    name='my new connection',
    description='my desc',
    # ...other fields (see [Connection Schema](#connection-schema) below)
)
id = response['app']['id']

// Set up the outbound apps service
OutboundAppsService outboundAppsService = descopeClient.getManagementServices().getOutboundAppsService();

// Create a connection
OutboundAppRequest request = new OutboundAppRequest();
request.setName("my new connection");
// ...other fields (see [Connection Schema](#connection-schema) below)

OutboundAppCreateResponse response = outboundAppsService.createApplication(request);
String id = response.getId();

// Create a connection
appRequest := &descope.CreateOutboundAppRequest{
    OutboundApp: descope.OutboundApp{
        Name:        "my new connection",
        Description: "my desc",
        // ...other fields (see Connection Schema below)
    },
    ClientSecret: "your-client-secret", // optional
}

app, err := descopeClient.Management.OutboundApplication().CreateApplication(ctx, appRequest)
if err != nil {
    // Handle error
}
id := app.ID

POST /v1/mgmt/outbound/app/create
Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>
Content-Type: application/json

{
  "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))
});

# Update a connection (overrides all fields)
descope_client.mgmt.outbound_application.update_application(
    id='my-connection-id',
    name='my updated connection',
    # ...other fields (see [Connection Schema](#connection-schema))
)

// Update a connection (overrides all fields)
OutboundAppRequest request = new OutboundAppRequest();
request.setId("my-connection-id");
request.setName("my updated connection");
// ...other fields (see [Connection Schema](#connection-schema))

outboundAppsService.updateApplication(request);

// Update a connection (overrides all fields)
app := &descope.OutboundApp{
    ID:   "my-connection-id",
    Name: "my updated connection",
    // ...other fields (see Connection Schema)
}

clientSecret := "your-client-secret" // optional, can be nil
app, err := descopeClient.Management.OutboundApplication().UpdateApplication(ctx, app, &clientSecret)
if err != nil {
    // Handle error
}

POST /v1/mgmt/outbound/app/update
Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>
Content-Type: application/json

{
  "app": {
    "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');

# Delete a connection by id
descope_client.mgmt.outbound_application.delete_application(
    id='my-connection-id'
)

// Delete a connection by id
outboundAppsService.deleteApplication("my-connection-id");

// Delete a connection by id
err := descopeClient.Management.OutboundApplication().DeleteApplication(ctx, "my-connection-id")
if err != nil {
    // Handle error
}

POST /v1/mgmt/outbound/app/delete
Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>
Content-Type: application/json

{
  "id": "my-connection-id"
}

Load a Connection

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

# Load a connection by id
connection = descope_client.mgmt.outbound_application.load_application(
    id='my-connection-id'
)

// Load a connection by id
OutboundApp connection = outboundAppsService.loadApplication("my-connection-id");

// Load a connection by id
connection, err := descopeClient.Management.OutboundApplication().LoadApplication(ctx, "my-connection-id")
if err != nil {
    // Handle error
}

GET /v1/mgmt/outbound/app/{id}
Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>

Load All Connections

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

# Load all connections
connections_res = descope_client.mgmt.outbound_application.load_all_applications()
for connection in connections_res['apps']:
    # do something
    pass

// Load all connections
OutboundApp[] connections = outboundAppsService.loadAllApplications();
for (OutboundApp connection : connections) {
    // do something
}

// Load all connections
connections, err := descopeClient.Management.OutboundApplication().LoadAllApplications(ctx)
if err != nil {
    // Handle error
}
for _, connection := range connections {
    // do something
}

GET /v1/mgmt/outbound/apps
Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>

Connection Schema

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

Connection Fields

Field	Type	Required	Description
`id`	string	Optional (create)	Unique identifier for the connection. Auto-generated if not provided during creation.
`name`	string	Required	Display name for the connection.
`description`	string	Optional	Human-readable description of the connection.
`logo`	string	Optional	URL or path to the connection logo.
`clientId`	string	Optional	OAuth client ID from the provider. Required for OAuth connections.
`clientSecret`	string	Optional	OAuth client secret from the provider. Required for OAuth connections.
`discoveryUrl`	string	Optional	OAuth discovery URL for automatic endpoint configuration.
`authorizationUrl`	string	Optional	OAuth authorization endpoint URL. Required if `discoveryUrl` is not provided.
`authorizationUrlParams`	array	Optional	Additional parameters to include in authorization requests.
`tokenUrl`	string	Optional	OAuth token endpoint URL. Required if `discoveryUrl` is not provided.
`tokenUrlParams`	array	Optional	Additional parameters to include in token exchange requests.
`revocationUrl`	string	Optional	OAuth token revocation endpoint URL.
`defaultScopes`	array of strings	Optional	Default OAuth scopes to request for all connections.
`defaultRedirectUrl`	string	Optional	Default redirect URL after successful OAuth flow.
`callbackDomain`	string	Optional	Domain to use for OAuth callbacks. Defaults to project domain.
`pkce`	boolean	Optional	Enable PKCE (Proof Key for Code Exchange) for OAuth flows.
`accessType`	string	Optional	OAuth access type (e.g., "offline" for refresh tokens).
`prompt`	array of strings	Optional	OAuth prompt parameters (e.g., ["consent", "select_account"]).
`appType`	string	Optional	Type of application. Will always be "custom" for manually created connections.

URL Parameter Structure

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

Field	Type	Required	Description
`key`	string	Required	The parameter name.
`value`	string	Required	The parameter value.

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']
};

connection = {
    'name': 'Google Contacts',
    'description': 'Access Google Contacts API',
    'logo': 'https://example.com/logo.png',
    'client_id': 'your-client-id',
    'client_secret': 'your-client-secret',
    'authorization_url': 'https://accounts.google.com/o/oauth2/v2/auth',
    'token_url': 'https://oauth2.googleapis.com/token',
    'default_scopes': ['https://www.googleapis.com/auth/contacts.readonly'],
    'default_redirect_url': 'https://app.example.com/callback',
    'callback_domain': 'app.example.com',
    'pkce': True,
    'access_type': 'offline',
    'prompt': ['consent']
}

OutboundAppRequest request = new OutboundAppRequest();
request.setName("Google Contacts");
request.setDescription("Access Google Contacts API");
request.setLogo("https://example.com/logo.png");
request.setClientId("your-client-id");
request.setClientSecret("your-client-secret");
request.setAuthorizationUrl("https://accounts.google.com/o/oauth2/v2/auth");
request.setTokenUrl("https://oauth2.googleapis.com/token");
request.setDefaultScopes(Arrays.asList("https://www.googleapis.com/auth/contacts.readonly"));
request.setDefaultRedirectUrl("https://app.example.com/callback");
request.setCallbackDomain("app.example.com");
request.setPkce(true);
request.setAccessType("offline");
request.setPrompt(Arrays.asList("consent"));

app := &descope.OutboundApp{
    Name:        "Google Contacts",
    Description: "Access Google Contacts API",
    Logo:        "https://example.com/logo.png",
    ClientID:     "your-client-id",
    AuthorizationURL: "https://accounts.google.com/o/oauth2/v2/auth",
    TokenURL:     "https://oauth2.googleapis.com/token",
    DefaultScopes: []string{"https://www.googleapis.com/auth/contacts.readonly"},
    DefaultRedirectURL: "https://app.example.com/callback",
    CallbackDomain: "app.example.com",
    Pkce:        true,
    AccessType:  "offline",
    Prompt:      []string{"consent"},
}

appRequest := &descope.CreateOutboundAppRequest{
    OutboundApp:  *app,
    ClientSecret: "your-client-secret",
}

{
  "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",
  "authorizationUrlParams": [
    {
      "key": "hd",
      "value": "example.com"
    }
  ],
  "tokenUrl": "https://oauth2.googleapis.com/token",
  "tokenUrlParams": [],
  "defaultScopes": ["https://www.googleapis.com/auth/contacts.readonly"],
  "defaultRedirectUrl": "https://app.example.com/callback",
  "callbackDomain": "app.example.com",
  "pkce": true,
  "accessType": "offline",
  "prompt": ["consent"],
  "appType": "custom"
}

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.

Was this helpful?

Ask AI about this page

On this page