Skip to main content

Manage tenant and workspace configurations

Learn how to export, import, and patch SecureAuth platform tenant and workspace configurations using the Configuration Promotion APIs.

This guide provides insights into these APIs and demonstrates how they streamline configuration management for your tenants and workspaces.

SecureAuth configuration APIs

SecureAuth provides Config Promotion APIs to export, import, and patch configurations for workspaces, tenants, and customer-deployed SecureAuth platforms.

These APIs simplify configuration management and support automation for both SaaS and self-hosted platforms.

Workspace configuration APIs

The workspace configuration APIs offer four endpoints to manage configurations:

Tenant configuration APIs

The tenant configuration APIs mirror the workspace APIs, providing four endpoints for managing tenant-level configurations.

These are useful for organizations managing multiple workspaces or tenant-wide settings such as Identity Pools, custom MFA settings, and custom themes

Customer-deployed tenant configuration APIs

For customer-deployed environments, the Tenant Management (also known as Root) APIs extend tenant configuration management with global operations. These APIs are not available for SaaS customers and apply only to self-hosted SecureAuth deployments:

Prerequisites

Note

To test the Configuration Promotion APIs, contact Support to enable the tree_dump_tenant feature flag.

For customer_deployed SecureAuth platforms, enable the feature flag in your platform configuration files.

Export configuration APIs

Export endpoints let you manage tenant and workspace configurations by exporting the current setup. Use them for tasks like initial imports, patching, or backups.

Find the latest example calls and responses for the Export Endpoints in the Configuration Promotion API documentation.

Tip

When using curl, add -o /full/path/to/export.json to save the results directly to a file.

Export response options

Control the export response using the with_credentials parameter.

  • with_credentials = true – Exports all credentials, such as JSON Web Key Sets (JWKS), secrets, and certificates.

  • with_credentials = false (default) – Exports credentials as null or empty objects.

    Note

    Public keys, like JWKS in DCR settings, are always included.

Export API limitations

Keep these limitations in mind:

  • You can export broken tenant and workspace configurations, but you cannot import or patch them.

  • Exported data may include workspace-specific details like redirect_uris in client applications. Update or remove these values before importing or patching.

  • Few tenant-specific references, such as the tenant name, may appear in exported configurations. Replace or eliminate them to avoid issues.

  • Identity Pools are not included in workspace exports.

    • If you have SecureAuth Authentication Providers attached to your workspace, first use tenant configuration APIs or Identity Pools APIs to export or import Identity Pool configurations.

Import configuration APIs

Import endpoints allow you to make wholesale changes to tenant or workspace configurations. If conflicts occur, the target configuration is overridden with the provided values. These endpoints are typically used for one-time tasks, like initial imports or configuration restores.

Find the latest example calls and responses in the SecureAuth Configuration Promotion API documentation.

Insert mode

The optional mode query parameter defines how to handle conflicts during import. For example, if both tenants have client applications with the same ID, SecureAuth resolves conflicts as follows:

  • mode=ignore (default) – Keeps the target configuration and ignores incoming changes.

  • mode = fail – Stops the import and returns an error.

  • mode = update – Overwrites the target configuration with the incoming changes.

Import API limitations

Keep these limitations in mind:

  • The import process fully overrides the target configuration. Use the the Patch configuration APIs for incremental changes instead.

    Warning

    Only use the import API if you want to overwrite the entire configuration. Use the Export configuration APIs to export the target configuration as a backup before importing.

  • If the JSON for import was exported with with_credentials = false, SecureAuth regenerates credentials (e.g., JWKS, client_secrets) during the import. Without a prior backup, these credentials cannot be recovered.

Patch configuration APIs

Use the patch endpoints to make iterative changes to tenant or workspace configurations. These APIs are essential for configuration promotion and automation..

Find the latest example calls and outputs in the Config Promotion API documentation.

Tips for patching

  • Use curl with the -d @/full/path/to/patch.json option to supply JSON Merge Patch contents directly from a file.

  • Ensure the JSON Patch conforms to RFC 7396 (preferred) or RFC 6902. SecureAuth recommends RFC 7396 for smoother patching.

Insert mode

The mode query parameter resolves conflicts during patching:

  • mode = ignore – Keeps the target configuration and ignores incoming changes.

  • mode = fail – Stops the patch and returns an error.

  • mode = update (default) – Applies the incoming changes to overwrite conflicting target values.

Patch API limitations

Keep these points in mind when using the patch APIs:

  • Broken configurations. Patching a workspace or tenant with invalid configurations may produce mixed results. For example, adding a SecureAuth Authentication Provider without an existing Identity Pool returns a 204 response, but the IDP isn’t created.

  • Error cases. Not all errors and messages are fully defined; some cases may still evolve.

  • Manual changes. Direct updates to the target tenant or workspace configuration can create conflicts and lead to unexpected patch results.

  • Special cases:

    • SecureAuth Authentication Providers require tenant configuration or Identity Pool APIs to handle Identity Pool configurations before patching.

    • Custom Themes must exist in the target tenant before patching a workspace bound to them.

For smooth operations, use a JSON Patch Tool to create patches based on RFC 7396. For detailed examples, see JSON Patch Tool

RFC 6902 vs RFC 7396: Choosing the right API

SecureAuth offers two API options to fit different configuation needs:

For simpler and smoother patching, SecureAuth recommends the RFC 7396 JSON Merge Patch API.

JSON Patch API (RFC 6902)

The JSON Patch API is best for small, targeted changes when you know the exact modifications required. It processes a series of operations, applying each one to the target configuration until all are complete or an error occurs.

Example

Target configuration:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "code",
            "token"
       ]
    }
  }
}

Patch operations:

[
{ "op": "replace", "path": "/clients/sample-client-id/client_name", "value": "demo-application" },
{ "op": "add", "path": "/clients/sample-client-id/response_types", "value": "id_token" }
]

Result:

{
 "clients":{
    "sample-client-id":{
       "client_name":"demo-application",
       "response_types": [
            "code",
            "token",
            "id_token"
       ]
    }
  }
}

The patch changes the client name and adds id_token to the response types.

JSON Merge Patch API (RFC 7396)

The JSON Merge Patch API simplifies larger configuration updates. It’s ideal for automated or scripted changes, using a syntax that mirrors the target configuration.

Example

Original configuration:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "token"
       ],
       "scopes": [
            "email",
            "profile",
            "openid",
            "offline_access"
       ]
    },
    "demo-client-id":{
     "client_name":"demo-application"
    }
  }
}

JSON merge patch:

{
 "clients":{
    "sample-client-id":{
       "response_types": [
            "code",
            "token",
            "id_token"
       ],
       "scopes": [
            "email",
            "profile",
       ]
    },
    "demo-client-id": null
  }
}

Result:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "code",
            "token",
            "id_token"
       ],
       "scopes": [
            "email",
            "profile",
       ]
    }
  }
}

This patch leaves client_name unchanged, modifies response_types and scopes, and completely removes demo-client-id.

In this section: