Connections

Connections vs. Outbound Apps

Connections and Outbound Apps provide the same capability (a token vault for OAuth tokens and API keys at the user or tenant level, with Descope managing storage and refresh), but they are separate objects in the Console. Connections live under Agentic Identity Hub → Connections; Outbound Apps live under Connect → Outbound Apps. A Connection you create here does not appear under Outbound Apps, and vice versa. Use Connections when building agents and MCP servers; use Outbound Apps for vaulting third-party tokens in a traditional application.

The Connections page is where you create and manage the credential vault your agents use to reach third-party services. From here you can:

Create connections to OAuth providers (Google, Slack, GitHub, and others) or API-key based services, so agents can retrieve credentials at runtime without holding long-lived secrets
View all connections in your project and inspect stored tokens and their status
Manage tokens: view, manually refresh, or delete stored access tokens and API keys per user or tenant

Connections work across both MCP server and direct agent integration patterns. Any agent that needs to call a third-party API retrieves its credential from Connections at the moment of use rather than from a config file or environment variable.

Connections support both OAuth providers (for interactive login and consent) and API-key based services (for machine or user-supplied secrets). Your MCP server retrieves these credentials at runtime using Descope SDKs or APIs, ensuring external tokens are managed centrally and never hardcoded in your infrastructure.

If you're building AI agents or MCP servers that need access to external services (e.g., Google Calendar, Salesforce), Connections handle secure storage, token refresh, and access control. Your tools can reliably retrieve user/tenant-scoped OAuth tokens or API keys whenever they need to call third-party APIs.

Keep credentials off the agent

An agent can fetch a Connection token directly, but the recommended pattern puts a Resource, an MCP server or gateway, between the agent and the vault.

The agent authenticates to the Resource; the Resource pulls the API key or external OAuth token from Connections at runtime and calls the downstream service. That way long-lived third-party secrets are never delivered to the agent.

How It Works

Create a Connection
- Choose a preconfigured OAuth provider, or create a custom connection for any service (including API key storage).
Storing Tokens
- Use Descope SDKs or APIs to connect users/tenants to OAuth providers or to collect and store API keys.
Fetching Tokens
- Descope securely stores and manages all tokens and API keys, making them available for backend or agent use.

Creating a Connection

To set up a connection in Descope, follow the steps in our Creating a Connection guide.

Storing Connection Tokens

Note

You can only add tenant-level tokens directly within the Descope Console.

Creating a Connection only defines the provider. To vault a credential, you run a user or tenant through the provider's OAuth consent once (or collect an API key). There are four ways to do this, covered in detail in Storing Connection Tokens:

Backend Connect API: Your server obtains a connection URL and redirects the user through consent. This powers Adaptive Connect for MCP servers (returning a connect URL to the client for URL elicitation) and lets web apps build their own connect UI.
Descope Flows: Connect during original authentication / consent so the token is vaulted before the agent needs it — ideal inside your MCP server's consent flow.
Outbound App Widget: Out-of-band connect when users sign into your platform; the agent fetches the vaulted token later when a tool runs.
Descope Console: Paste a tenant-level API key in the Console (Token tab → Add Tenant Token). Intended for Descopers vaulting organization-owned keys, typically against a tenant for your own company with workforce SSO.

Token Management

Note

Refresh token expiration is not available for all providers.

Certain providers, like Instagram, have a fixed refresh token expiration time, and cannot be changed.

Once you have tokens stored with Descope, associated with your Connection, you can view them from within the token management tab. These are all of the things you can view for each token:

ID: System-generated ID pairing that user's consent to the application.
App ID: The configured application ID which coincides with the token ID.
Associated User: The user ID of the user who's associated with the consent.
Scopes: The consented scopes correlate to the user's consent to the application.
Access Token Expiration: Expiration of the current access token for the user's consent.
Refresh Token: Boolean indicating whether a refresh token is available.
Refresh Token Expiration: Expiration of the current refresh token for the user's consent.
Last Refreshed: The last time the user's access token was refreshed.
Last Refresh Error: If applicable, the last error encountered while trying to refresh the user's access token.
Token Subject: The user reference on the provider side. For this example, it is associated with the unique user ID of the user's Google account.
Access Token Type: Specifies the format or method the access token uses, such as Bearer or MAC, which determines how it is used for authentication and authorization.
Tenant ID: The tenant ID of the tenant associated with the consent.

Viewing a connection's token management in Descope

You can also view the tokens in plain text, manually refresh any of the tokens (if OAuth-based), or delete any tokens from this tab.

You can also remove tokens using our SDKs, documented here.

Fetching Your Connection Tokens

Once your users/tenants are connected and have tokens stored in our Connections vault, you can start fetching the tokens to access third-party APIs within your MCP server or with your agents.

Was this helpful?