Acronis #CyberFit Developer Training Part I: Get Started, Authorization, and Tenant Management

This is the first part of the course focusing on the essential intro, authorization flow, and tenants management.

The hands-on manuals, hands-on code, and presentations are for the full course.

Business Automation and account management training course is focused on the Acronis Cyber Platform Account Management API. It provides you the knowledge and hands-on experience you’ll need to successfully automate the provisioning of accounts, applications, offering items, quota management, user creation, and activation, as well as reports management and much more.

About the course

  • Scenario-Based Course
  • 3 Hands-on-Labs with detailed step-by-step manuals in PowerShell, Bash, and Postman
  • Includes updated module to support Acronis Cyber Protect solutions
  • Best practices and advice for integrators
  • Dedicated training module for managing SKU mappings

You will learn how to

  • Automate accounts provisioning
  • Manage applications, offering items and quota
  • Create and aсtivate users
  • Manage reports
  • Create Billing Automation for SKUs

The training’s Hands-on Manuals

The training’s Hands-on Code

  1. Bash
  2. PowerShell
  3. Postman
  4. Python

The training's presentation in PDF

Account Management API

REST API and Account Management API Intro

Learn about developing with the Acronis Cyber Platform APIs with our documentation, code examples, public Postman collections, forum, and more. 

Account Management API Authorization Flow

A JWT token with a limited time to life approach is used to securely manage access of any API clients, like our scripts, for the Acronis Cyber Cloud. 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 to issue a JWT token.

PI Client credentials can be generated in the Management Portal.

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. 

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

Treat API Clients as a specific service account with access to your cloud. All internal security policies applied to your normal account operations should be in place for API Clients. Thus, don't create new API Clients if you don't really require and disable/delete unused API Clients through the Management Console or API Calls.

You can receive a client_secret only once, just at the issue time. If you lose your client_secret further you must reset the secret for the client through the Management Console or API Calls. Please, be aware, that all the tokens will be invalidated.

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 time-to-live and must be renewed/refreshed before the expiration time. 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 in the response JSON is a time when the token will expire in Unix time format -- seconds from January 1, 1970. Here we assume that we will renew/refresh a token 15 minutes before the expiration time.

Tenants Management

In Acronis Cyber Cloud, entities that have a relationship with the Service Provider (such as a reseller or end-customer) are represented by the resource type known as tenants which are managed from the Clients tab. Each tenant can have 1 or more user account for access to services and for service administration and are managed from the Users tab. All tenant types with the exception of Customer can be nested to create a hierarchy so as to match business, organization, or relationship structure.

Types of Tenants

  • Partner: Represents a service provider that resells services, can create and have 1 or more Partner, Customer, and Folder tenants under it 
  • Customer: Represents an end-customer company or organization that uses services, can create and have 1 or more Unit tenants under it 
  • Unit: Represents a sub-unit of an end-user company such as a department, location, or group of devices, can create and have 1 or more Unit tenants under it 
  • Folder: Special tenant type used for grouping similar child tenants together, can also be used as a “template” since child tenants created within a Folder will “inherit” the Services settings of the folder

In API, Tenants and User accounts are represented as JSON objects. Within each tenant, services, also known as Applications in API and their corresponding Offering Items (Data Sources, Locations, etc.), can be enabled/disabled. User accounts have Access Policies (roles) for access to Applications within a tenant and Personal Tenants for user account usage quotas and usage info.

Tenant Hierarchy

Tenant Hierarchy

So now we can securely access the Acronis Cyber Platform API calls. In this topic, we discuss how to create a partner and customer tenants.

Assuming that we create the API client for our root tenant, we start by retrieving the API Client tenant information using GET request to /clients/{client_id} end-point. Then, using received tenant_id information as a parent_id parameter and kind equal to partner, we build a JSON body for POST request to /tenants end-point to create a partner. 

To create a customer tenant, this is absolutely the same process as for a partner, the only difference is kind equal to customer.

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

Create a Tenant

Only a name, a parent tenant id, and a kind are required to create a tenant. 

{
    "name": "{my_tenant_name}",
    "parent_id": "{parent_tenant_id}",
    "kind": “{kind_of_tenant}"
}

A tenant name must be unique in your hierarchy. Customer tenants are created in the trial mode. This mode means that usage data for the created tenant will not be included in monthly service usage reports for billing.

The created tenant doesn’t contain any enabled applications or offering items.

Update a Tenant

To update a tenant, only a current version is required, and you can specify only changed values.

Delete a Tenant

Deleting a tenant is not a reversible operation and results in the following:

  • All sub-tenants are deleted.
  • All user accounts within this tenant and all its sub-tenants are deleted.
  • All services enabled within this tenant and all its sub-tenants stop operating.
  • All service-related data (e.g., backups, synced files) of this tenant and all its sub-tenants are deleted.

Basic Tenant Information Calls and Navigation

No caption

Search for a Tenant

To search for tenants or users:

GET /search

With the following query parameters
  • tenant – the root tenant for tenants hierarchy to search
  • text – text to search
  • limit – limit output (default 10).
The following property values are checked in tenants
  • Tenant name – name
  • First name – firstname in the contact object
  • Last name – lastname in the contact object
  • Customer ID – customer_id (Custom Id from Management Console)

Manage Trials for a Customer Tenant

By default, customers are created in a 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 end-point then change mode property to production in the received JSON, then, finally, update the pricing using PUT request to /tenants/{customer_tenant_id}/pricing end-point with a new pricing mode JSON.

Note This switch is non-revertible.

Summary

With the first part of Acronis #CyberFit Developer Training for Bussiness Automation, you now know how to authorize to use Account Management API and manage tenants.

The next part of Acronis #CyberFit Developer Training for Bussiness Automation is about offering items and applications management.

Updated
Stas Pavlov
Technology Evangelist
Account management API
Acronis Cyber Platform