Managing Environments

Descope allows you to create many projects to fit your needs. You could have multiple projects for different businesses, or you could have a development, staging, and production projects for the various stages of your development and testing. Descope makes it easy to manage your projects and migrate configurations between projects.

Creating Projects

Within the Descope console, clicking the project drop down in the top right allows you to create new projects by clicking the + Project button at the bottom of the list of your projects. When you create a new project, you can provide the project with a name and choose whether it is production or non-production. You can later change whether the project is production or non-production from the Project Settings page within the console. Note that selecting production or non-production does not effect the features within the project. This is an internal identifier for Descope to see which projects are marked as production.

Managing Secrets in Environments

When working with environments, it's essential to note Descope's behavior in handling API keys and other related secrets around connectors and OAuth provider configurations. The below outlines how Descope manages secrets and credentials during project cloning, exporting, and importing.

During the cloning of a project, secrets are cloned to the new project with all of their current configuration and settings.
While exporting a project, the exported project zip will contain the connector or OAuth provider configuration; however, the credentials will be removed to prevent the export of secrets.
It is possible to import connectors and OAuth providers with their credentials and secrets when importing a project. The examples below outline how you would import connectors with secrets, but the same applies to OAuth providers.
If you have exported a project and are importing that project to another project that already has the same connectors or OAuth providers configured, the secrets stored within the project you are importing to will be retained (unless overridden by editing the secrets within the exported zip), but the other settings of the connector or OAuth provider will be updated. Please also see the documentation around secret placeholders for more information on overriding secrets.

Importing Secrets

When you export your project, you will receive a zip file with the contents, such as the one below.

assets.json

body-xxx.html

embeddedlink.json

enchantedlink.json

connectors.json

http-xxx.json

smtp-xxx.json

twilio-xxx.json

flow.json

screen-1.json

dark.json

light.json

styles.json

environment.json

attributes.json

project.json

ssoapps.json

The connectors directory includes the configuration of each connector associated your Project.

{
  "configuration": {
    "authentication": {
      "apiKey": {},
      "basic": {},
      "method": "bearerToken"
    },
    "baseUrl": "https://api.sendgrid.com/v3/mail",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "insecure": false
  },
  "contentVersion": "",
  "description": "Sendgrid Generic HTTP",
  "id": "xxxx",
  "name": "Sendgrid Generic",
  "status": "enabled",
  "templateId": "http"
}

To import the secrets within a new project, add them to the downloaded files within the zip, zip the entire directory back up, and then import them to your new project. This will then import the secrets into your project and allow the connectors to be immediately used without further configuration of the connectors after the import.

Secret Placeholders

When you export a project with connectors or OAuth providers configured with secrets, you will see that the secrets will have a placeholder of PLACEHOLDER_VALUE. There are two options when handling placeholders within the secrets of the configuration files.

If you leave PLACEHOLDER_VALUE in the exported configuration file, the secrets in the project you are importing will be retained.
If you would like to override the configured secrets within the project, you would change the PLACEHOLDER_VALUE to be the correct secrets for the project.
Removing the line containing the placeholder or replacing "PLACEHOLDER_VALUE" with null or "" will clear the configured value from the secret on import.

Below are examples of connector and OAuth provider configurations with PLACEHOLDER_VALUE.

{
  "configuration": {
    "authentication": {
      "apiKey": {},
      "basic": {},
      "bearerToken": "PLACEHOLDER_VALUE",
      "method": "bearerToken"
    },
    "baseUrl": "https://example.com",
    "hmacSecret": "PLACEHOLDER_VALUE",
    "hmacSignEntireRequest": true,
    "includeHeadersInContext": true,
    "insecure": false
  },
  "contentVersion": "",
  "description": "",
  "id": "xxxxx",
  "name": "Example Connector",
  "status": "enabled",
  "templateId": "http"
}

Cloning Projects

From the Project Settings page Descope allows you to clone your projects. This allows you to create a duplicate of your current project. A use case for this would be cloning your development project to create a staging and production project. This will copy your flows, styles, project settings, authentication method configurations, email templates, etc.

Exporting Projects

Within Descope, you can export a project from the Project Settings page. This exports your flows, styles, project settings, authentication method configurations, email templates, etc. You can then import the downloaded zip file into another project, or selectively import your flows or styles into another project.

Importing Projects

Descope allows you to import an exported project to another existing project. This is useful when you are working between development, staging, and production projects. Once you have tested your configurations within your environments, you can export and import the project into the next level in your deployments.

Partial Project Importing

When migrating a project from one environment to another, it's important to ensure that only the necessary components are transferred, allowing for a seamless integration without overwriting critical configurations in the new project. This document outlines how you can selectively remove specific folders or files within the exported project folder. By doing so, you prevent these items from being imported into the new project, ensuring that the specific values aren't overwritten.

To exclude specific elements during the import process, you should:

Export your project: Begin by exporting the entire project from your current environment. This is documented here.
Modify the export: Before importing, remove or edit the project.json file to exclude specific keys. Additionally, delete any files or folders that you do not wish to import.
Import the modified project: Once you have customized your project export by removing unwanted elements, import the project into your new environment.

Note

You can also use the Descope API import endpoint with the excludes argument with the documented flags to exclude certain items from an export as well.

Customizable Elements in `project.json`

The project.json file contains several keys that you can choose not to include in your import. Removing or altering these keys from project.json before importing ensures that the corresponding settings in your new project remain unchanged:

domain
trustedDomains
tokenResponseMethod
selfProvisioning
rotateJwt
cookiepolicy
refreshTokenExpiration
stepupTokenExpiration
sessionTokenExpiration
keySessionTokenExpiration
inviteUrl
inviteEmail
inviteSms
inviteMagicLink
conformanceJwt
inactivity

An example of the project.json file looks like this:

Terminal

{
  "conformanceJwt": false,
  "cookiePolicy": 3,
  "domain": "",
  ...
}

Non-Modifiable Files and Folders

Aside from the specific keys in project.json, there are various files and folders that you can choose to include or exclude entirely from your import. However, it's important to note that individual elements within these files cannot be modified from their original export. Here's what you can choose to exclude:

All JSON files under the auth directory control different authentication mechanisms. You have the option to include or exclude these files as a whole:

auth/magicLink.json
auth/enchantedLink.json
auth/embeddedLink.json
auth/otp.json
auth/totp.json
auth/sso.json
auth/oauth.json
auth/webauthn.json
auth/password.json

The following directories and files are crucial to the project's functionality but can be selectively included or excluded based on your requirements:

styles folder
flows folder
connectors folder
roles.json
ssoApps.json

Any file or folder not listed above, should not be altered, as that could affect the success of the project import.

Conclusion

Customizing your project import allows you to maintain the integrity of your new project's configuration, preventing unintended overwrites and ensuring a smooth transition. Carefully review and modify the exported project files and folders according to the guidelines provided to achieve the desired outcome in your new project environment.

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Update Project Name

This endpoint allows you to update the current project's name.

// Args
//   name (str): The new name for the project.
const name = "New Project Name"
 
const resp = await descopeClient.management.project.updateName(name)
 
if (!resp.ok) {
  console.log(resp)
  console.log("Failed to update project name.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated project name.")
}

Export Project

This endpoint allows you to export the current project.

// Args
//   None
 
const resp = await descopeClient.management.project.export()
 
if (!resp.ok) {
  console.log(resp)
  console.log("Failed to export project.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully exported project.")
  console.log(resp.data)
}

Import Project

This endpoint allows you to import all settings and configurations into the current project. Use with caution, this endpoint overrides any current configuration.

// Args
//   files (<Record<string, any>): The raw JSON dictionary of files, in the same format as the one returned by calls to export.
const files = {
	"files": {
		...
	}
}
 
const resp = await descopeClient.management.project.import(files)
if (!resp.ok) {
  console.log(resp)
  console.log("Failed to import project.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully imported project.")
}

Clone Project

This function allows you to clone the current project, including its settings and configurations.