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:
-
Export configuration that allows you to globally export your entire ACP deployment configuration for every tenant.
-
Import configuration that allows you to globally export your entire ACP deployment configuration for every tenant.
-
Export tenant configuration that allows you to export a specific tenant’s configuration only.
-
Import tenant configuration that allows you to import a configuration for a specific tenant only.
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
-
You have access to the system workspace.
-
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
-
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.
-
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
-
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.
-
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
-
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.
-
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
-
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.
-
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 toignore
- ACP ignores the changes that come from your configuration import. -
mode
set tofail
- ACP stops import processing and returns an error. -
mode
set toupdate
- ACP updates the tenant’s configuration with the value provided in the request.
The default value for the mode
parameter is ignore
.