Project Snapshot

A project snapshot is a portable export of your Descope project configuration. Use snapshots to back up settings, promote changes across environments (for example, development to staging to production), or track configuration in source control.

The layout below matches a typical CLI or Console export. Exact files vary by what you have configured — for example, fgaschema.txt appears when Fine-Grained Authorization is set up, and auth/ only lists methods that exist in the project.

Snapshot Structure

When you export a project, Descope writes the configuration to a folder of JSON files (and related text) plus subdirectories. Each top-level path maps to a configuration area in your project.

Quick Reference

Admin Portal

adminportal.json stores the hosted Admin Portal configuration: whether the portal is enabled, which login flow and style to use, the portal title, and which widgets appear (and in what order).

Promoting this file keeps the same portal layout across environments. It only selects which widgets the portal surfaces, while the widget implementations themselves live under widgets/.

Applications

applications.json holds an applications array of Federated Apps: apps where Descope is the IdP, or hosts login for a Custom app. Each entry has an id, name, enabled state, optional template id, and a protocol block (oidc, saml, or WS-Fed) with settings like login page URL and claims.

The default OIDC app (descope-default-oidc) is included when present. Client secrets follow the usual secrets rules, so they are not checked in as plaintext.

This file is only for Federated Apps. Inbound Apps show up elsewhere in the snapshot: consent and CIBA flows, Resources and dynamic registration templates, and inbound-app fields in attributes.json.

Attributes

attributes.json exports custom attribute schemas (the definitions you create in the Console), not the values stored on individual users or tenants. Attributes are grouped by entity. For example, inboundApp holds Inbound App custom attributes, and the same pattern applies for user or tenant attributes when those exist in the project.

Each definition includes name, type, display name, options for select types, and edit or view permissions. The actual values on users, tenants, or apps stay out of the snapshot because they are runtime data.

Authentication Methods

The auth/ directory has one JSON file per authentication method configured in the project. Common files include:

Each file stores that method's project-level settings — templates, selected connectors, redirects, policy toggles, and related Console options. Messaging templates often point at assets/ with asset: references instead of inlining HTML. OAuth provider client secrets use placeholders when exported.

Connectors

connectors/ includes connectors.json (an index of connector IDs) plus one JSON file per connector (id, name, type, description, and configuration).

Sensitive fields in configuration (for example SendGrid apiKey) are exported as PLACEHOLDER_VALUE. On import, the destination keeps existing secrets unless you override them — see Managing Environments.

Fine-Grained Authorization

When your project has an FGA schema, the snapshot includes fgaschema.txt: the same AuthZ DSL you edit in the Console Code view (types, relations, and permissions). Promote this file alongside roles.json when environments should share the same ReBAC model.

If FGA is unused, this file may be absent from the export.

Outbound Apps

outboundapps.json has two top-level arrays:

clientSecret values are empty or placeholder on export; inject secrets on import when the target project needs them.

Roles

roles.json contains a roles array. Each role has an id, name, description, and a list of permission names. Importing applies those RBAC definitions so flows, apps, and APIs that reference role names stay consistent across environments.

Resources

resources.json captures your project's Resources for environment promotion as infrastructure-as-code. Typical top-level keys:

MCP server configuration moves between environments this way: each MCP server is a Resource with "type": "mcp". If that resource uses a dynamic registration template (useTemplate or dynamicRegistrationTemplateId), the template is exported under dynamicRegistrationTemplates. API Resources skip that concept entirely.

Everything in resources.json is applied with the rest of the project when you run descope project snapshot import.

Assets

The assets/ directory holds binary and text files referenced elsewhere in the snapshot — flow or widget images, OAuth provider logos, email HTML, and plain-text bodies. assets.json is the manifest: its mapping object ties each snapshot path and field to asset filenames.

Asset files use content-based names with a type prefix. The hash in each filename is derived from the file contents, so identical assets share the same name across exports.

Other snapshot files reference assets with an asset: prefix followed by the filename — for example "emailBody": "asset:emailbody-xxxxx.txt" in project.json, or "logo": "asset:img-xxxxx.svg" on an OAuth provider.

When exporting with the Descope CLI, pass --no-assets to skip extracting asset files into the snapshot directory.

Flows

The flows/ directory holds every flow in the project. flows.json is the index: it lists each flow by flow ID, and each ID has a matching subdirectory under flows/.

{
  "flows": [
    "sign-in",
    "sign-up-or-in",
    "inbound-apps-user-consent",
    "ciba-authentication"
  ]
}

Each flow folder contains the flow logic, metadata, and one JSON file per screen.

Consent and CIBA flows used by Inbound Apps or MCP (for example inbound-apps-user-consent) are ordinary flow folders here. The Resource and template settings that reference those flows live in resources.json.

To work with a single flow outside a full project snapshot, use descope flow export or descope flow convert to move between snapshot format (a flow folder) and a single JSON file.

Styles

The styles/ directory holds every style in the project, including custom styles. styles.json is the index: it lists each style by style ID (and a componentsVersion), and each ID has a matching JSON file under styles/.

{
  "componentsVersion": "3.14.10",
  "styles": [
    "custom-style-1-dark",
    "custom-style-1-light",
    "dark",
    "light",
    "sso-suite-default-dark",
    "sso-suite-default-light"
  ]
}

Each style JSON file defines only the changes from Descope’s default light or dark styles — overrides rather than full copies — so customizations stay manageable on top of the built-in appearance.

{
  "components": {
    "container": {
      "id": {
        "ROOT": {
          "--descope-container-background-color": "var(--descope-colors-primary-main)"
        }
      }
    }
  },
  "globals": {
    "colors": {
      "secondary": {
        "contrast": "#FFFFFF",
        "dark": "#355313",
        "highlight": "#9DDA58",
        "light": "#7BC32B",
        "main": "#588B1FFF"
      }
    }
  },
  "name": "Custom-Style-1",
  "type": "flows"
}

Widgets

The widgets/ directory holds every widget in the project. widgets.json is the index: it lists each widget by widget ID, and each ID has a matching subdirectory under widgets/.

{
  "widgets": [
    "access-key-management",
    "applications-portal",
    "audit-management",
    "role-management",
    "user-access-key-management",
    "user-management",
    "user-profile"
  ]
}

Each widget folder contains metadata and one JSON file per screen (similar to flows).

The widgets/ directory also contains a flows/ subdirectory with widget flows. There is a flows.json index; each flow ID has a folder under widgets/flows/ with contents.json, metadata.json, and per-screen JSON files.

The hosted Admin Portal decides which of these widgets to show through adminportal.json. widgets.json lists every widget in the project, whether or not the portal uses it.

Project Metadata