Creating Inbound Apps

There are two main methods for creating Inbound Apps in Descope:

  1. Manual Creation - Create and configure inbound apps manually through the Descope console
  2. 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:

  1. Navigate to the Inbound Apps page of the Descope console.
  2. Click + Add Inbound App to create a new Inbound Application.
  3. Define the App Name and Description (both can be edited later).

Creating an inbound app in Descope

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).

Configuring an inbound app's details in Descope

Scopes

Scopes define what permissions and user data the third-party application can access.

Configuring an inbound app's scopes in Descope

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.

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).

Configuring an inbound app's connection information in Descope

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:

  1. Navigate to the Inbound Apps page of the Descope console.
  2. In the top right, click on the Inbound App Settings icon.

Inbound App Settings

  1. Toggle Enable dynamic client registration for your project.

Enabling Dynamic Client Registration

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

Approved Scopes List

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.

Flow Hosting URL

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:

cursor://anysphere.cursor-retrieval/oauth/*/callback

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

{
  "client_name": "My MCP Client",
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "read:user write:user",
  "client_uri": "https://myclient.com",
  "logo_uri": "https://myclient.com/logo.png",
  "description": "A client application for MCP server integration",
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "permissions_scopes": [
    {
      "name": "read:user",
      "description": "Read user information",
      "roles": ["user"]
    }
  ],
  "attributes_scopes": [
    {
      "name": "profile",
      "description": "Access to user profile information",
      "user_attribute": "email"
    }
  ]
}

Registration Response

Upon successful registration, the endpoint returns:

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "client_id_issued_at": 1640995200,
  "client_secret_expires_at": 0,
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "read:user write:user",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic"
}

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.

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.

Inbound application flow components in Descope

Note

This is mandatory for FHIR and highly recommended for MCP integrations.

To integrate a consent screen into your flow:

  1. Use a subflow to keep your authentication flow consistent.
  2. 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.

Checking if the user has granted consent

  1. 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.

Update User Consent

  1. If the user denies consent, prompt them to review or return.
  2. Customize the flow as needed for your app's logic and design.

For more consent-based flow examples, visit our Flow Template library in the Descope Console.

Example of a completed consent flow

This setup ensures a smooth user experience while enforcing consent-based access control.

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.

Viewing inbound app consents in Descope

Next Steps

Once your Inbound App is configured, integrate it into your external applications by using Descope's OAuth authentication flows.

Was this helpful?