Inbound Apps with SDKs

Use the Descope Management SDK to create, update, patch, delete, and load Inbound Apps (third-party applications in the Management API), as well as manage secrets and consents. The Management SDK requires a management key.

For an overview of inbound app concepts and console setup, see Creating Inbound Apps.

Note

The preferred method of defining scopes for your backend services is to use a Resource and define a policy for access to it.

You can still define permissionsScopes and attributesScopes on the inbound app itself if you prefer.

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

Application Management

Create, update, load, and delete inbound apps, and manage client secrets.

Create Inbound Application

This operation creates a new inbound application with the provided details. Using the SDK or Management API is one way to register a non-confidential inbound app without Dynamic Client Registration (DCR).

Note

Create/update field support varies by SDK. Python, Go, and Ruby accept additional options such as forcePkce / force_pkce, defaultAudience / default_audience, customAttributes / custom_attributes, and JWT Bearer settings. The Node.js typed options currently cover the core fields below; use the Management API for the full request schema.

// Args:
//   name (String): Name (required)
//   description (String): Optional description
//   logo (String): Optional logo URL
//   loginPageUrl (String): Optional login page URL
//   approvedCallbackUrls (String[]): Optional list of approved callback URLs
//   permissionsScopes (InboundAppScope[]): Array of permission scopes, can be empty (required)
//   attributesScopes (InboundAppScope[]): Optional array of attribute scopes

const {
  data: { id, cleartext: secret },
} = await descopeClient.management.inboundApplication.createApplication({
  name: 'my new app',
  description: 'my desc',
  logo: 'data:image/png;..',
  approvedCallbackUrls: ['example.com'],
  permissionsScopes: [
    {
      name: 'read_support',
      description: 'read for support',
      values: ['Support'],
    },
  ],
  attributesScopes: [
    {
      name: 'read_email',
      description: 'read user email',
      values: ['email'],
    },
  ],
  loginPageUrl: 'http://example.com/login',
});

Update Inbound Application

This operation updates an existing inbound application, overwriting all fields with the provided values.

Note

All provided parameters are used as overrides to the existing application. Empty fields will override populated fields.

// Args:
//   id (String): App ID (required)
//   name (String): Name (required)
//   description (String): Optional description
//   logo (String): Optional logo URL
//   loginPageUrl (String): Optional login page URL
//   approvedCallbackUrls (String[]): Optional list of approved callback URLs
//   permissionsScopes (InboundAppScope[]): Array of permission scopes, can be empty (required)
//   attributesScopes (InboundAppScope[]): Optional array of attribute scopes

await descopeClient.management.inboundApplication.updateApplication({
  id: 'app-id',
  name: 'my updated app',
  description: 'my desc',
  logo: 'data:image/png;..',
  approvedCallbackUrls: ['example.com'],
  permissionsScopes: [
    {
      name: 'read_support',
      description: 'read for support',
      values: ['Support'],
    },
  ],
  attributesScopes: [
    {
      name: 'read_email',
      description: 'read user email',
      values: ['email'],
    },
  ],
  loginPageUrl: 'http://example.com/login',
});

Patch Inbound Application

This operation updates only the provided fields of an inbound application.

// Args:
//   id (String): App ID (required)
//   name (String): Optional name
//   description (String): Optional description
//   logo (String): Optional logo URL
//   loginPageUrl (String): Optional login page URL
//   approvedCallbackUrls (String[]): Optional list of approved callback URLs
//   permissionsScopes (InboundAppScope[]): Optional array of permission scopes
//   attributesScopes (InboundAppScope[]): Optional array of attribute scopes

await descopeClient.management.inboundApplication.patchApplication({
  id: 'app-id',
  description: 'my updated desc',
  logo: 'data:image/png;..',
  loginPageUrl: 'http://example.com/login',
});

Delete Inbound Application

This operation deletes an inbound application by its ID.

Note

This action is irreversible. Use carefully.

// Args: id (String): App ID

await descopeClient.management.inboundApplication.deleteApplication('app-id');

Delete Inbound Applications (Batch)

This operation deletes multiple inbound applications in a single request.

Note

This action is irreversible. Use carefully.

// Args:
//   appIds (String[]): Array of inbound app IDs to delete

await descopeClient.management.inboundApplication.deleteApplicationBatch(['app-id-1', 'app-id-2']);

Load Inbound Application

This operation loads a specific inbound application by its ID.

// Args: id (String): App ID

const { data: app } =
  await descopeClient.management.inboundApplication.loadApplication('app-id');

Load Inbound Application by Client ID

This operation loads a specific inbound application by its client ID.

try {
    InboundApp app = inboundAppsService.loadApplicationByClientId("client-id");
} catch (DescopeException de) {
    // Handle the error
}

Get Inbound Application Secret

This operation retrieves the application's secret by its ID.

// Args: id (String): App ID

const {
  data: { cleartext: secret },
} = await descopeClient.management.inboundApplication.getApplicationSecret('app-id');

Rotate Inbound Application Secret

This operation rotates the application's secret and returns the new secret.

// Args: id (String): App ID

const {
  data: { cleartext: newSecret },
} = await descopeClient.management.inboundApplication.rotateApplicationSecret('app-id');

Load All Inbound Applications

This operation loads all inbound applications in the project.

const { data: apps } =
  await descopeClient.management.inboundApplication.loadAllApplications();
apps.forEach((app) => {
  // Do something
});

Search and revoke user or tenant consents granted to inbound apps. For the Console consent view, see Managing User Consent.

Delete User Consents for Inbound App

This operation deletes user consents for an inbound app. At least one identifying field must be set.

// Args:
//   consentIds (String[]): Optional array of consent IDs to delete
//   appId (String): Optional inbound app ID
//   userIds (String[]): Optional array of user IDs
// At least one of consentIds, appId, or userIds must be provided

await descopeClient.management.inboundApplication.deleteConsents({
  userIds: ['user-id-1'],
});

Delete Tenant Consents for Inbound App

This operation deletes tenant consents for an inbound app. At least one identifying field must be set.

// Args:
//   consentIds (String[]): Optional array of tenant consent IDs to delete
//   appId (String): Optional inbound app ID
//   tenantId (String): Optional tenant ID
// At least one of consentIds, appId, or tenantId must be provided

await descopeClient.management.inboundApplication.deleteTenantConsents({
  tenantId: 'tenant-id',
});

Search Consents for Inbound Apps

This operation searches consents for inbound apps. All fields are optional and can be used to filter results.

Note

The Ruby SDK does not currently support searching consents. Use the Search consents Management API instead.

// Args:
//   appId (String): Optional inbound app ID to filter by
//   userId (String): Optional user ID to filter by
//   consentId (String): Optional consent ID to filter by
//   page (Number): Optional page number for pagination

const { data: consents } =
  await descopeClient.management.inboundApplication.searchConsents({
    appId: 'app-id',
    page: 2,
  });

Was this helpful?

On this page