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.

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 a custom domain 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.

Note

Users, tenants and access keys are not cloned.

// Args
//   name (str): The new name for the project.
const name = "New Project"
//   tag(str): Optional tag for the project. Currently, only the "production" tag is supported.
 
const resp = await descopeClient.management.project.clone(name, null)
if (!resp.ok) {
  console.log(resp)
  console.log("Failed to clone 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 cloned project.")
  console.log(resp.data)
}

Was this helpful?