February 10, 2021

Prototyping Acronis Cyber Platform API Solutions with Postman: Account Management

In years of the API economy when API is around us, it has become a common task to test how API fits a solution architecture and approach. There are a lot of ways to create a prototype and one of the commonly used is with Postman. While Postman can be applied in various scenarios, in this document we will be focusing on API.

Acronis Cyber Platform API on Postman API Network

We have published all available public APIs:

Account Management API
Task Manager, Activities and Alerts API
Cyber Files API
Cyber Notary API
Agents API

The Acronis Cyber Platform exposes a set of REST API to allow partners to integrate existing and create new solutions.

You can view documentation with real examples of JSON requests and responses or run the collection from Postman. The collections are updated on a weekly basis and contain examples of API calls for Acronis Cyber Cloud with the latest API changes. The collections are fully parametrized and even scripted in common scenarios to prevent copy-pasting errors. Runners for some base tasks are also included.

Runners are like scripts from API calls inside the Postman. You can use environment variables with post- and pre-call scripts. It gives you a simple and customizable approach to prototyping solutions based on the Acronis Cyber Platform.

Acronis Account Management API Postman Collection Overview

More than 150 API calls in Acronis Account Management API Postman Collection cover various scenarios from authorization to Agent installation.

Acronis Account Management API Collection in Postman Web UI

The API calls are grouped into 17 folders; 3 of them represent Postman Runners for common provisioning tasks, and 1 is for training purposes:

Authorization
Tenants management
Applications, offering items, and quota management
Users management
Impersonate a user
Agent registration tokens
Locations and storage management
Reports management
Search
Basiс platform info
Well-Known
Legal Documents
External OAuth Integration
Runner: Create a partner and assign them all available editions and offering items
Runner: Create a partner and lock updates from the Management Console for them
Runner: Create a customer and assign them Cyber Protect Standard edition and all available offering items

Folder names directly reflect topics or scenarios that they cover. As the collection is fully parameterized it is 100% ready for re-use and scripting with Runners. The included Runners can be used as examples of basic proof-of-concept scripting.

Let’s have a quick look into the basic scenarios, like authorization and provisioning.

To use the Postman collection, go to https://documenter.getpostman.com/view/5763797/SzzrYuH2 and click the Run in Postman button at the top-right corner of the screen.

You need to have the Postman application installed on your workstation.

How to authorize to access Account Management API

A JWT token with a limited time-to-live is used to securely manage access to Acronis Cyber Cloud for any API clients, like your scripts and integrations. Using a login and password for a specific user is not a secure and manageable way to create a token, but technically it's possible. Thus, we create an API client with a client id and a client secret to use as credentials when issuing a JWT token. To create an API Client, we call the /clients endpoint with POST request specifying in the JSON body of the request a tenant we want to have access to. To authorize this request, the Basic Authorization with user login and password for Acronis Cyber Cloud is used.

Starting Acronis Cyber Cloud 9.0 API Client credentials can be generated in the Management Portal and it's the recommended way how to create an API Client.

Creating an API Client is a one-time process. As the API client is used to access the API, treat it as credentials, and store it securely. Also, do not store the login and password in the scripts themselves.

In this Postman Collection, it is expected that the Acronis Developer Sandbox is used. It is available for registered developers at Acronis Developer Network Portal. So the base URL for all requests https://dev-cloud.acronis.com is used. Please, replace it with the correct URL for your production environment if needed. For more details, please, review the Authenticating to the platform via the Python shell tutorial from the Acronis Cyber Platform documentation.

For demo purposes, we use a user’s credentials to issue an API Client. The same technic can be used if your security policy has security credentials lifetime policy. The resulting API client belongs to the tenant where this user is registered. You should add your logic as to what tenant should be used for the API Client creation.

A generated client has inherited access rights from a user used for the generation but is disconnected from them. You don't need to issue a new client even if the user account is removed from Acronis Cloud.

For simplicity, this flow was built for a case with 2FA not enabled. In case 2FA is enabled, you need either use the ACC 9.0 Management Console to create an API Client and skip the firsts steps or use a service account for that task.

The flow

1. Using an icon at the right of the drop-down list, open Postman environment in the edit mode. Enter your username and your password in the imported Acronis Cyber Platform Development environment for basic authentication.

2. Open settings for the imported collection and set the base_url variable. It's used for all API calls and indicates your Acronis data center.

3. Expand the imported collection.

4. Expand The training flow folder.

5. Open Get self info using Basic Authentication request in the Postman and click Send.

6. You receive information regarding the authenticated user.

7. We create an API Client for a specific tenant. For our hands-on lab, we create a client for your root tenant. So you need to put tenant_id value to the my_tenant_id variable. To do this, select the tenant_id JSON response value without quotas and press the right mouse button for PC. Then select Set: Acronis Cyber Platform Development from the drop-down menu and my_tenant_id from the drop-down menu.

8. When successfully set up the my_tenant_id variable, check it in the environment.

9. Open Create an API Client request and then select the Body tab. You can see parametrized JSON body request to create an API Client. Click Send.

client_name is used as a display name for an API Client in the Management Console.

10. You should receive a JSON response body as below.

{
    "token_endpoint_auth_method": "client_secret_basic",
    "created_by": "bfa9d672-35ee-4cad-b987-024d145f7fe3",
    "redirect_uris": [],
    "data": {
        "client_name": "API.Client"
    },
    "status": "enabled",
    "created_at": "2020-02-26T11:20:39+00:00",
    "tenant_id": "53b471e1-50dd-4557-ae6d-f687923121d4",
    "client_secret": "aa6f81cb2b7f4306aeeb16815ea71ef3",
    "registration_access_token": "5fef399909ca48929c9e8d04350af3e1",
    "type": "api_client",
    "client_id": "c5597043-98ed-4474-ad09-d90a34513651",
    "client_secret_expires_at": 0
}

11. Add client_id and client_secret from the JSON response body to the same-named variables as it was done for my_tenants_id.

12. Open the Management Console and check that you successfully created an API Client.

How to issue a token to access the API

A client_id and a client_secret can be used to access the API through Basic Authorization but it's not a secure way as mentioned above. It's more secure to have a JWT token with a limited life-time and implement a renew/refresh logic for that token.

To issue a token /idp/token end-point is called using POST request with param grant_type equal client_credentials and content type application/x-www-form-urlencoded with Basic Authorization using a client_id as a user name and a client_secret as a password.

A token has a time-to-live and must be renewed/refreshed before it expires. The best practice is to check before starting any API calls sequence and renew/refresh if needed.

Currently, the default time-to-live to a token for the API is 2 hours.

expires_on is a time when the token will expire in Unix time format -- seconds from January 1, 1970. Here we assume that you will renew/refresh a token as soon as you receive a 401 answer in Postman.

The flow

1. Open Issue a JWT token request in The Postman and then the Body tab. Make sure you use x-wwwform-urlencoded as a Content-Type and pass grant_type equal to client_credentials.

2. Click Send. You should receive a JSON response body as bellow

{
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImU0NGE4ZGE0LTljYWUtNGYxZC05NGJmLTk2MDcwODFjNWI2ZCJ9… …ylBfHxqlreG5YntPQVDwYdL5MvHriCF6svqiGDXSpCRBtVejUM6RmpCNXvAYhO_BtUjdYQ",
    "token_type": "bearer",
    "expires_on": 1598973813,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImU0NGE4ZGE0LTljYWUtNGYxZC05NGJmLTk2MDcwODFjNWI2ZCJ9…. …yc2N34KOGkiHKaTCbfUJokdkJ_i3U--VfXjc957cdncAghUa7JEqPYoBTA_0C1wpTMRP6WNeDQbSl1Tkh0XLlGJ6L8WBMFw"
}

3. Add access_token value without quotas from the JSON response body to the same-named variable.

4. We are ready to make another API calls.

How to create partner, customer, and user tenants and set offering items

So now you can securely access the Acronis Cyber Platform API calls. This topic explains how to create partners and customer's tenants, enable all available offering items for them, and then create a user for the customer and activate the user by setting a password.

Assuming that we create the API client for our root tenant, we start from retrieving the API Client tenant information using GET request to /clients/{{client_id}} endpoint. Then, using the received tenant_id information as a parameter and kind equals partner type, we build a JSON body for POST request to the /tenants end-point to create a partner. Next, we are going to enable all applications and offering items for the tenants. Briefly, we take all available offering items for the parent tenant of the partner or the customer using a GET request to /tenants/{{parent_tenant_id}}/offering_items/available_for_child endpoint with needed query parameters specifying edition and kind of the tenant. Then, we need to enable these offering items for the partner or the customer using a PUT request to /tenants/{{tenant_id}}/offering_items endpoint with all offering items JSON in the request body and appropriate {{tenant_id}}.

The following ‘kind’ values are supported: partner, folder, customer, unit.

The process is similar for a customer, the only difference is that kind equals customer in the request body JSON and /offering_items/available_for_child parameters.

By default, customers are created in trial mode. To switch to production mode, we need to update customer pricing. To perform this task, we start from requesting current pricing using a GET request to /tenants/{{customer_tenant_id}}/pricing endpoint then change mode to productionin the received JSON, then, finally, update the pricing using a PUT request to /tenants/{{customer_tenant_id}}/pricing endpoint with a new pricing JSON.

Please, be aware, that this switch is non-revertible.

Finally, we create a user for this customer. At first, we check if a login is available using a GET request to /users/check_login endpoint with username parameter set to an expected login. Then, we create a JSON body for POST request to /users endpoint to create a new user.

The created user is not active yet. To activate a user we can either send an activation e-mail to the specified email or manually set a password. Sending an activation e-mail is the preferable way, as in this case the user can select a password. For demonstration purposes, we use a set password and a fake e-mail. To set a password we send a simple JSON and POST request to /users/{{user_id}}/password endpoint.

How to create a partner

1. Open Create a partner tenant request in the Postman and then Body tab. Check the JSON body. It uses my_tenant_id as a parent tenant id and should create a partner named MyFirstPartner. Click the Send button. You should receive a JSON response body as below

{
    "kind": "partner",
    "contact": {
        "state": null,
        "organization_size": null,
        "created_at": "2020-09-01T13:49:42.379967+00:00",
        "city": null,
        "zipcode": null,
        "external_id": null,
        "industry": null,
        "email_confirmed": null,
        "address1": null,
        "id": "88551ee4-2c2d-46c8-9245-2c5fd54a44db",
        "website": null,
        "firstname": "",
        "updated_at": "2020-09-01T13:49:42.379971+00:00",
        "country": null,
        "lastname": "",
        "phone": null,
        "address2": null,
        "email": "",
        "title": null
    },
    "brand_uuid": "7bbee631-da82-47e1-8774-2843f4e81236",
    "has_children": false,
    "internal_tag": null,
    "language": "en",
    "brand_id": 7545,
    "contacts": [],
    "enabled": true,
    "owner_id": null,
    "version": 1,
    "id": "8acc01fc-3231-44fa-ba93-4cec4c48f70d",
    "default_idp_id": "11111111-1111-1111-1111-111111111111",
    "parent_id": "531789f2-2be9-42af-8474-18177593c77b",
    "customer_type": "default",
    "pricing_mode": "production",
    "update_lock": {
        "enabled": false,
        "owner_id": null
    },
    "name": "Postman Demo Runner Partner",
    "mfa_status": "disabled",
    "ancestral_access": true,
    "customer_id": null
}

2. If a partner with this name already exists, you receive an error like below

{
    "error": {
        "code": 1004,
        "message": "The tenant with this name already exists.",
        "details": {
            "info": "The tenant with this name already exists.",
            "addition": [
                {
                    "existed_group_id": 1600755
                }
            ]
        },
        "context": {
            "existed_group_id": 1600755
        },
        "domain": "PlatformAccountServer"
    }
}

3. Add id value without quotas from the JSON response body to the partner_tenant_id variables the same way as you have done it before for other variables.

4. Open Get available offering items for a partner tenant request in the Postman and then Params tab. We are ready to request offering items available for the created tenant. To specify edition and type use the edition and kind variables. Make sure that Acronis Cyber Platform Development environment kind variable is set to partner and edition is set to per_workload, and then click Send. You should receive a JSON response body as below.

{
    "items": [
        {
            "application_id": "6e6d758d-8e74-3ae3-ac84-50eb0dff12eb",
            "type": "infra",
            "locked": false,
            "name": "pw_storage",
            "usage_name": "storage",
            "infra_id": "019097a6-114f-4418-bd54-e01ef049f209",
            "measurement_unit": "bytes",
            "quota": {
                "version": 0,
                "value": null,
                "overage": null
            },
            "status": 1,
            "edition": "per_workload"
        },

…
…      
{
           "application_id": "6e6d758d-8e74-3ae3-ac84-50eb0dff12eb",
            "type": "count",
            "locked": false,
            "name": "pw_gsuite_seats",
            "usage_name": "gsuite_seats",
            "measurement_unit": "quantity",
            "quota": {
                "version": 0,
                "value": null,
                "overage": null
            },
            "status": 1,
            "edition": "per_workload"
        }
    ]
}

5. For simplicity purposes, we enable all available offering items for a partner with Cyber Protect Edition. Select the response JSON body, press the right mouse button (on Windows) and from the drop-down menu select Copy. We have copied the JSON to a buffer for further usage.

6. Open Set offering items for a partner tenant request in the Postman and then Body tab. You can see an example of offering items JSON body. Select all the JSON request body, press the right mouse button (on Windows) and from the drop-down menu select Paste. Then replace the JSON root element items with offering_items. Now we are ready to update the partner offering items; click Send. You should receive a JSON response body as below. It represents a set of offering items for the tenant.

{
    "items": [
        {
            "application_id": "6e6d758d-8e74-3ae3-ac84-50eb0dff12eb",
            "type": "infra",
            "locked": false,
            "name": "pw_storage",
            "usage_name": "storage",
            "infra_id": "019097a6-114f-4418-bd54-e01ef049f209",
            "measurement_unit": "bytes",
            "quota": {
                "version": 0,
                "value": null,
                "overage": null
            },
            "status": 1,
            "edition": "per_workload"
        },

…
…      
{
           "application_id": "6e6d758d-8e74-3ae3-ac84-50eb0dff12eb",
            "type": "count",
            "locked": false,
            "name": "pw_gsuite_seats",
            "usage_name": "gsuite_seats",
            "measurement_unit": "quantity",
            "quota": {
                "version": 0,
                "value": null,
                "overage": null
            },
            "status": 1,
            "edition": "per_workload"
        }
    ]
}

7. Open the Management Console and check that you have successfully created a partner and enabled all offering items for Cyber Protect Edition.

How to create a customer

1. Open Create a customer tenant request in the Postman and then Body tab. Check the JSON body. It uses partner_tenant_id as a parent tenant id and should create a customer named MyFirstCustomer.

2. Click Send. You should receive a JSON response body similar to the partner flow.

3. Add id value without quotas from the JSON response body to the customer_tenant_id variables the same way as you have done it before for other variables.

4. Open Get available offering items for a customer tenant request in the Postman and then Params tab. We are ready to request offering items available for the created tenant. To specify the edition and type the edition and kind variables are used. Make sure that Acronis Cyber Platform Development environment kind variable set to customer and edition set to per_workload and click Send. You should receive a JSON response body the same as for the partner flow.

5. For simplicity purposes, we enable all available offering items for a customer with per_workload edition. Select the response JSON body, click the right mouse button (on Windows) and from drop-down menu select Copy. We have copied the JSON to a buffer for further usage.

6. Open Set offering items for a customer tenant request in the Postman and then Body tab. You can see an example of offering items JSON body. Select all the JSON request body, click the right mouse button (on Windows), and from the drop-down menu select Paste. Then replace the JSON root element items with offering_items. So, now we a ready to update the partner offering items, click the Send button. You should receive a JSON response body the same as for the partner flow. It represents a set of offering items for the tenant.

8. Open the Management Console and check that you successfully create a customer and enable all offering items for Cyber Protect Edition.

How to create and activate a user

1. Open Check login availability request in the Postman and then Params tab. It's required to have a unique login for a user. So, before creating a user we need to check login availability.

2. Please, check the Acronis Cyber Platform Development environment login variable set to the login you want to use.

3. Click the Send button. If the login is available you receive an empty response body and 204 response code. Otherwise, change the Acronis Cyber Platform Development environment login variable to another value and repeat step 3.

4. Open Create a new user for a customer request in the Postman and then Body tab. You can see a parametrized JSON request body to create a user for a customer with tenant id equal to customer_tenant_id and login being login. In this example, we use fake e-mail, first and last names. Click Send. You should receive a JSON response body as below.

{
    "mfa_status": "disabled",
    "tenant_id": "886edd90-60f7-474a-8553-3be7db4daf8c",
    "language": "en",
    "personal_tenant_id": "2f7e2fcd-81ab-4c55-8fe8-f28dc5704ea5",
    "business_types": [],
    "idp_id": "11111111-1111-1111-1111-111111111111",
    "created_at": "2020-02-04T09:53:56.175938+00:00",
    "enabled": true,
    "version": 1,
    "notifications": [
        "quota",
        "reports",
        "backup_daily_report"
    ],
    "activated": false,
    "id": "8630bd54-6707-4f2c-8220-23a351b2097d",
    "contact": {
        "zipcode": null,
        "lastname": "Last-stas.test.2020",
        "state": null,
        "city": null,
        "phone": null,
        "country": null,
        "email": "stas.test.2020@example.com",
        "firstname": "First=stas.test.2020",
        "address2": null,
        "address1": null
    },
    "login": "stas.test.2020"
}

5. Add the id value without quotas from the JSON response body to the user_id variables the same way as you have done it before for other variables.

6. Add personal_tenant_id value without quotas from the JSON response body to the user_personal_tenant_id variables the same way as you have done it before for other variables.

7. Open the Management Console and check that you have successfully created a user.

A created user is not active yet. To activate the use, choose between sending an activation e-mail or manually setting a password.

Sending an activation e-mail is the preferable way, as in this case the user can set their own password. In our example, we use a set password and a fake e-mail.

8. Open Activate a user by setting a password request in the Postman and then Body tab. You can see a simple JSON request body to set a user password. Click Send.

9. If the call is successful you receive an empty response body and 204 response code.

10. Open the Management Console and check that you successfully activate the user.

The created user has no roles assigned. It means it can't use any service. To enable services/applications you need to assign an appropriate role to a user.

All operations with the user account roles are located under the /users/{{user_id}}/access_policies endpoint.

Summary

Now you know how to use Acronis Account Management API Postman collection for basics scenarios. You can find the full collection of calls and try them out in Acronis Sandbox available after registering on Acronis Developer Portal.

Check other collections at the Postman API Network:

Task Manager, Activities and Alerts API
Cyber Files API
Cyber Notary API
Agents API

Get started today, register on Acronis Developer Portal and see the code samples available, you can also review solutions available in the Acronis Cyber Cloud Solutions Portal.

Updated February 11, 2021