Creating Inbound Apps
There are two main methods for creating Inbound Apps in Descope:
- Manual Creation - Create and configure inbound apps manually through the Descope console
- Dynamic Client Registration (DCR) - Allow OAuth clients to register themselves automatically
Method 1: Manual Inbound App Creation
To manually create an Inbound App in Descope, follow these steps:
- Navigate to the Inbound Apps page of the Descope console.
- Click
+ Add Inbound App
to create a new Inbound Application. - Define the App Name and Description (both can be edited later).
Once the application is created, you can configure its settings, including:
- App Details
- Scopes (Permissions & User Data)
- Connection Information
- Consent Management
Inbound App Details
This section allows you to configure key information about the inbound app.
- Logo (Optional): Upload a logo for the application. This will be displayed during user consent flows.
- Inbound App Name (Required): The name of the third-party application.
- Description (Optional): A short description of the app.
- App ID (System Generated): A unique identifier for the application (cannot be changed).
Scopes
Scopes define what permissions and user data the third-party application can access.
Permission Scopes
Permission scopes allow the inbound app to perform specific actions on behalf of the user or tenant. If using Descope's RBAC model, these scopes are mapped to roles, ensuring that access is granted only to authorized users.
- Name (Required): The unique identifier for the permission scope.
- Description (Required): A brief summary of the permission.
- Roles (Optional): Assign roles if RBAC is enabled, restricting scope access to users with the appropriate role.
User Information Scopes
These scopes define what user data is shared with the third-party application. The data can include built-in Descope attributes (e.g., email, name) or custom attributes that your organization defines.
- Name (Required): The unique identifier for the user data scope.
- Description (Required): A summary of the data being shared with the third-party application.
- User Attribute (Required): The specific user attribute mapped to this scope. Access to this data follows Descope's role-based authorization (RBAC) model, ensuring proper permissions are enforced.
User Consent and Role-Based Restrictions
The end user will not be able to update user consent through the flow if they do not have the appropriate role associated with the scope they are requesting.
This means:
- If a scope requires a role that the user does not have, they will not be able to grant consent for it.
- Only users with the correct RBAC roles will have the ability to approve or manage consent for those specific scopes.
By enforcing role-based user consent, Descope ensures that only authorized users can share sensitive data or grant permissions, maintaining strong access control and compliance.
Connection Information
This section contains configuration details needed to integrate the inbound app with Descope.
Note
If you have a custom domain configured, the system-generated URLs will use your custom domain instead of api.descope.com
.
- Flow Hosting URL (Required): The URL where the consent flow is hosted. It can be:
api.descope.com
- Your custom domain
- A self-hosted instance of the consent flow.
- Approved Callback URLs (Optional): The URLs Descope is allowed to redirect users to after authentication.
- Client ID (System Generated): The unique identifier for the application.
- Client Secret (System Generated): The shared secret used for authentication.
- Discovery URL (System Generated): Provides OpenID Connect configuration details, including supported scopes, public keys, and endpoints.
- Issuer (System Generated): The issuer URL used for verifying identity tokens.
- Authorization URL (System Generated): The endpoint for initiating authentication (
https://api.descope.com/oauth2/v1/apps/authorize
). - Access Token URL (System Generated): The endpoint for retrieving access tokens (
https://api.descope.com/oauth2/v1/apps/token
).
Method 2: Dynamic Client Registration (DCR)
Dynamic Client Registration allows OAuth clients to register themselves with your OAuth server automatically, which is particularly useful for protecting MCP (Model Context Protocol) servers.
This feature enables seamless integration with MCP clients like Cursor and Claude Desktop that need to dynamically register as OAuth clients.
Enabling Dynamic Client Registration
To enable DCR for your project:
- Navigate to the Inbound Apps page of the Descope console.
- In the top right, click on the Inbound App Settings icon.
- Toggle Enable dynamic client registration for your project.
Once enabled, you can configure the following DCR settings:
Approved Scopes List
Note
Defining mandatory and optional scopes is useful for allowing the end user to control which scopes they grant to OAuth clients that dynamically register with your Descope project.
Configure the list of scopes that are approved for granting as part of the DCR process:
- Name: The name of the scope. This is what will be included in the scope parameter of the OAuth request, and in the OAuth tokens
- Description: A brief description of what the scope allows
- Roles: Map the scope to specific Descope roles for RBAC enforcement
- Mandatory: Toggle whether this scope is required for all DCR registrations
Note
We recommend setting as few scopes as possible to mandatory, and allowing the end user to grant more scopes if they choose to.
If you want to force the end user to grant consent to all scopes, you can set all of them to be mandatory.
Empty Scope Handling
By default, DCR handles empty scope requests automatically. This is useful when your OAuth client doesn't request any scopes automatically. You can toggle this behavior on or off based on your security requirements.
When your OAuth client authorizes with an inbound app created with DCR, without any scopes, the end user will simply be able to register the app, but the token will not include any scopes, and thus will not have access to any protected APIs that have scope validation. The consent screen will simply ask the user to "authorize" the app, without any additional information.
Flow Hosting URL
Set the Flow Hosting URL to the URL of the consent flow you wish to run for DCR registrations.
- Flow Hosting URL (Required): The URL where the consent flow is hosted. It can be:
api.descope.com
- Your custom domain
- A self-hosted instance of the consent flow.
Approved Redirect URLs
To restrict registration to specific applications, you can configure approved redirect URLs.
This ensures that only applications with matching redirect URLs can register through the DCR process, providing an additional layer of security.
For example, if you want to allow only certain OAuth clients to connect, you can use a pattern like:
In this example, the *
acts as a wildcard for the client-specific portion of the redirect URL.
If you are using Cursor MCP, the *
would match the mcpServer
name defined in your Cursor mcp.json
file.
Note
This pattern can be adapted for any OAuth client, not just MCP Clients. The Cursor example above demonstrates how you might use a wildcard to securely allow a family of related clients.
The /register
Endpoint
Note
If you don't enable DCR for your project, you will not see a /register
endpoint in your Inbound App well known configuration.
When DCR is enabled, clients can register themselves using the /register
endpoint. This endpoint accepts a POST request with the following parameters:
Required Parameters
- client_name (string): The name of the client application
- redirect_uris (array of strings): Array of redirect URIs that the client will use. Must contain at least one valid URL.
Optional Parameters
- client_uri (string): URL of the client's home page
- logo_uri (string): URL of the client's logo
- logo_content (string): Base64-encoded logo content
- scope (string): Space-separated list of requested scopes
- description (string): Description of the client application
- token_endpoint_auth_method (string): Authentication method for the token endpoint
- grant_types (array of strings): Array of grant types the client will use
- response_types (array of strings): Array of response types the client will use
- consent_flow_id (string): ID of the consent flow to use for this application
- login_page_url (string): Custom login page URL for the application
Example Registration Request
Registration Response
Upon successful registration, the endpoint returns:
Note
The client_secret is only returned once during registration. Make sure to store it securely as it cannot be retrieved later.
Registration Validation
The /register
endpoint validates requests against your DCR configuration:
- redirect_uris: Must contain at least one valid URL and match patterns in your approved redirect URLs
- scope: Must be from your approved scopes list
- client_name: Must be provided and non-empty
If validation fails, the endpoint returns an appropriate error response with details about what needs to be corrected.
Building a Consent Flow
Inbound Apps include additional flow components to allow your end users to easily provide consent to your OAuth server.
Inbound App Flow Components
There are two components in Descope flows created specifically for Inbound Apps:
- Inbound App Logo - Displays the app's configured logo and connection arrows.
- Inbound App Scopes - Automatically shows the scopes configured for the app, ensuring users can review permissions before proceeding.
Implementing a Consent Flow
To integrate a consent screen into your flow:
- Use a subflow to keep your authentication flow consistent.
- After authentication, check if the user has already granted consent using
thirdPartyApp.user.consented
.- If consent is given, proceed to the next step.
- If not, display the consent screen.
- Use the
Update User Consent
action to save the user's response. Here you can also pass in the amount of time that the user's consent is valid for, by either specifying a number or a dynamic value that you ask the user to provide in the consent screen.
- If the user denies consent, prompt them to review or return.
- Customize the flow as needed for your app's logic and design.
Example Consent Flow
For more consent-based flow examples, visit our Flow Template library in the Descope Console.
This setup ensures a smooth user experience while enforcing consent-based access control.
Managing User Consent
You will not be able to create an inbound app token, without the end user providing consent in the flow defined in your Flow Hosting URL. This will result in an error if you do not possess the consent screen and action within your flow.
The Consent tab provides visibility into which users have authorized the inbound app and what permissions they granted.
- Consent ID: A unique identifier for the user's consent.
- Scopes: The granted permissions.
- Associated User: The ID of the user who granted consent.
- Associated Tenant: The tenant ID, if applicable.
- Granting User: The user who authorized the app (e.g., an admin granting consent for a team).
- Expiration Time: The time that the user's consent expires.
- Creation Time: Timestamp when consent was given.
Next Steps
Once your Inbound App is configured, integrate it into your external applications by using Descope's OAuth authentication flows.
- Using Inbound Apps - Learn how to authenticate users with Descope as an IdP.
- Developing APIs to Support OAuth Scopes & Permissions - Secure your APIs with OAuth and manage user consent.
Inbound Apps
Discover how to configure inbound apps in Descope to streamline user consent, permissions, and integration with third-party platforms.
Integrating Inbound Apps
Learn how to integrate inbound apps with Descope to streamline OAuth authentication, manage user consent, and securely connect third-party applications.