Exporting and importing ACP tenants configuration using ACP API.

Learn how to export and import ACP tenant's configuration using API. You can move tenants' configuration between your different ACP deployments, or use it for configuration automation. You can also export and import the entire ACP configuration for all tenants.

About working with tenant configuration

With ACP system API you can export and import your tenants' configuration. There are four dedicated endpoints that allow you to do that:

Note

All of the configuration import/export endpoints return/accept JSON with the configuration.

Exporting/importing tenant’s configuration

With ACP system API, you can export and import a specific tenant’s configuration. There are many reasons to do it. It can be used for configuration automation or, for example, you can move tenant’s configuration between different ACP deployments. A company that delivers its services to financial institutions and uses ACP to protect their APIs, may want to import an Open-Banking-directive-compliant tenant’s configuration from one of their deployments to the deployment of their customers.

Prerequisites

  1. You have access to the system workspace.

  2. A client application that allows you to make requests to the token endpoint is created in the system workspace.

    Note

    To learn how to set up such application, see the Getting started with ACP REST API guide, section Preconfigure your workspace.

    Preconfigure your workspace describes how to create the client application that you need, but for the Admin workspace and admin APIs. What you need to do, is to create similar application in the System workspace and assign the manage_configuration scope to it.

Export configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn more

    If you need help with getting the token, see the Getting started with ACP REST API guide, section Call the token endpoint.

  2. Call the export tenant configuration endpoint

    Request example

    curl -o configuration.json --location --request GET 'https://{tid}.authz.cloudentity.io/api/system/{tid}/configuration' \
    -H 'Authorization: Bearer $AT'
    

    The {tid} path parameter is your tenant identifier.

    Replace the $AT variable with the access token that you got in the first step.

Result

Your tenant configuration is returned as JSON in the request response body. You can copy and save it or use the -o configuration.json curl request parameter (as provided in the request example) to save the response body to a JSON file.

The file is saved in the current location you are at when sending the curl request.

Import the configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn more

    If you need help with getting the token, see the Getting started with ACP REST API guide, section Call the token endpoint.

  2. Call the import tenant configuration endpoint.

    Request example

    curl --location --request PUT 'https://{tid}.authz.cloudentity.io/api/system/{tid}/configuration' \
    -H 'Authorization: Bearer $AT' \
    -d @configuration.json
    

    The {tid} path parameter is your tenant identifier.

    Replace the $AT variable with the access token that you got in the first step.

    You can either paste your JSON tenant configuration to your request or point to the file that contains the configuration using the -d @YourFileName.json parameter. If you are using a file to provide the request body content, you must make the request from the location the file is placed in or provide a whole path to your file, for example -d @path/to/your/file/YourFile.json.

    Tip

    You can see that in the example request, the request body parameter points to the configuration file that was saved after the request to the export tenant configuration endpoint.

    Before the import, you can, of course, modify the content of your configuration file and adjust it to your needs.

Result

Your tenant configuration is imported and available within ACP.

Exporting/importing global tenants configuration

Customers that use the on-premise version of the ACP deployment can use the global tenants' configuration export/import ACP REST APIs. The requirement to have the on-premise deployment comes from the fact, that you need to be able to access the system tenant of your deployment.

Using the Export configuration API you can export the configuration of all tenants available for your deployment. The response from this endpoint contains a JSON with all tenants and their configuration.

Export global configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Note

    To be able to get an access token, you must use the client credentials grant flow. An application with the client ID set to system is created for you in the System tenant by default. You can find the client secret that corresponds to your client application in your ACP deployment configuration.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn more

    If you need help with getting the token, see the Getting started with ACP REST API guide, section Call the token endpoint.

  2. Call the export configuration endpoint

    Request example

    curl -o configuration.json --location --request GET 'https://{tid}/api/system/configuration' \
    -H 'Authorization: Bearer $AT'
    

    The {tid} path parameter is your tenant identifier.

    Replace the $AT variable with the access token that you got in the first step.

Result

Your tenants' configuration is returned as a JSON in the request response body. You can copy and save it or use the -o configuration.json curl request parameter (as provided in the request example) to save the response body to a JSON file.

The file is saved in the current location you are at when sending the curl request.

Import the configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Note

    To be able to get an access token, you must use the client credentials grant flow. An application with the client ID set to system is created for you in the System tenant by default. You can find the client secret that corresponds to your client application in your ACP deployment configuration.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn more

    If you need help with getting the token, see the Getting started with ACP REST API guide, section Call the token endpoint.

  2. Call the import configuration endpoint.

    Request example

    curl --location --request PUT 'https://{tid}/api/system/configuration' \
    -H 'Authorization: Bearer $AT' \
    -d @configuration.json
    

    The {tid} path parameter is your tenant identifier.

    Replace the $AT variable with the access token that you got in the first step.

    You can either paste your JSON tenant configuration to your request or point to the file that contains the configuration using the -d @YourFileName.json parameter. If you are using a file to provide the request body content, you must make the request from the location the file is placed in or provide a whole path to your file, for example -d @path/to/your/file/YourFile.json.

    Tip

    You can see that in the example request, the request body parameter points to the configuration file that was saved after the request to the export configuration endpoint.

    Before the import, you can, of course, modify the content of your configuration file and adjust it to your needs.

Result

Your global tenants configuration is imported and available within your ACP deployment.

Insert mode

Both import endpoints have the optional mode query parameter available. This parameter defines what happens if there are any conflicts when importing your tenant configuration. For example, if a client already exists within ACP and you are trying to import a configuration that also has a client with this ID, there are the following ways ACP can handle the request:

  • mode set to ignore - ACP ignores the changes that come from your configuration import.

  • mode set to fail - ACP stops import processing and returns an error.

  • mode set to update - ACP updates the tenant’s configuration with the value provided in the request.

The default value for the mode parameter is ignore.