Authenticating to the platform

In this tutorial, we assume that you have an activated administrator account.

You will do the following:

  1. Register a third-party application as an API client via the management console of the cloud platform.

  2. Issue the API client an access token via POST /idp/token.

    With this token, the application will have the right to perform operations in the tenant and its sub-tenants on behalf of the administrator.

Before you start

  1. Start the Python shell and configure its session.

    As the result, the requests, json, and pprint modules should be loaded in the interactive shell and the following variable should be defined:

Registering an API client in the tenant

  1. To register an API client, follow the procedures described in the Acronis Cyber Cloud Partner’s Guide. When you will be asked to save the client ID, client secret and data center URL, define variables client_id, client_secret and base_url and assign them with the provided data:

    >>> client_id = '<your client ID>'
    >>> client_secret = '<your client secret>'
    >>> datacenter_url = '<your data center URL>'
    
  2. Assuming that your data center URL is https://eu2-cloud.acronis.com, the base URL to the Account Management API will be https://eu2-cloud.acronis.com/api/2.

    Define a variable named base_url, and then assign the value of the datacenter_url to it and append path to the API to this variable:

    >>> base_url = f'{datacenter_url}/api/2'
    >>> base_url
    'https://eu2-cloud.acronis.com/api/2'
    

Issuing the API client an access token

  1. Encode the client ID and client secret string using Base64 encoding and store the result in a variable:

    >>> from base64 import b64encode  # Used for encoding to Base64
    >>> encoded_client_creds = b64encode(f'{client_id}:{client_secret}'.encode('ascii'))
    
  2. Define a variable named basic_auth, and then assign an object with the Authorization key containing authentication data to this variable:

    >>> basic_auth = {
    ...     'Authorization': 'Basic ' + encoded_client_creds.decode('ascii')
    ... }
    
  3. Send a POST request to the /idp/token endpoint. The request should contain authentication data in the request headers and contain the grant_type field set to client_credentials in its body:

    >>> response = requests.post(
    ...     f'{base_url}/idp/token',
    ...     headers={'Content-Type': 'application/x-www-form-urlencoded', **basic_auth},
    ...     data={'grant_type': 'client_credentials'},
    ... )
    
  4. Check the status code of the response:

    >>> response.status_code
    200
    

    The 200 code means that the platform has authenticated the API client and issued the API client a token for accessing API endpoints (an access token). The response body text contains an encoded JSON object with this token and some other information.

    A different code means that an error has occurred. For the details, refer to “Status and error codes”.

  5. Convert the JSON text that the response body contains to an object, and then store this object in a variable named token_info:

    >>> token_info = response.json()
    >>> pprint.pprint(token_info)
    {'access_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImMwMD...',
     'expires_on': 1562910964,
     'id_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjI5ZT...',
     'token_type': 'bearer'}
    
  6. Define a variable named auth, and then assign an object, that will be used for constructing an Authorization header in API requests, to this variable:

    >>> auth = {'Authorization': 'Bearer ' + token_info['access_token']}
    >>> auth
    {'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImMwMD...'}
    

    You will need to specify this variable in every request to the API as follows:

    requests.get(f'{base_url}/clients/{client_id}', headers=auth)
  7. In order to access Task Manager API, update the base_url variable with the following path to the API:

    >>> base_url = f'{datacenter_url}/api/task_manager/v2'
    >>> base_url
    'https://eu2-cloud.acronis.com/api/task_manager/v2'
    

Now, your application is all set with the access to the Task Manager API.