Accessing the API

The following procedure describes how to fetch the URL of the data center where the user account is registered, and how to generate a token.

Before you start

  1. Start the Python shell and configure its session.

    As the result, the requests, json, pprint, hashlib and os.path modules should be loaded in the interactive shell.

  2. Define a variable named account_creds, and then assign the username and password to this variable:

    >>> account_creds = {
    ...     'username': 'JohnSmith',
    ...     'password': 'qwe123QWE'
    ... }
    

Fetching the URL of the data center

  1. Define a variable named cloud_url, and then assign the URL of the cloud platform to this variable:

    >>> cloud_url = 'https://cloud.acronis.com'
    
  2. Send a GET request to the /api/1/accounts endpoint. The request should contain the username of the user account in login query string parameter.

    >>> response = requests.get(f'{cloud_url}/api/1/accounts', params={'login': account_creds['username']})
    
  3. The endpoint always responds with code 200 and the response body contains the JSON text that looks as follows:

    {"login": "JohnSmith", "id": 0, "server_url": "https://eu2-cloud.acronis.com"}
    
  4. Store the data center URL in a variable that will be used in further requests:

    >>> server_url = response.json()['server_url']
    >>> server_url
    'https://eu2-cloud.acronis.com'
    
  5. Define a variable named base_url, and then assign the API base url to this variable:

    >>> base_url = f'{server_url}/api/notary/v2'
    

Generating a token

  1. Send a POST request to the /api/2/idp/token endpoint. The request should contain the grant_type field set to password, and corresponding user account credentials in username and password fields:

    >>> response = requests.post(
    ...     f'{server_url}/api/2/idp/token',
    ...     headers={'Content-Type': 'application/x-www-form-urlencoded'},
    ...     data={'grant_type': 'password', **account_creds},
    ... )
    
  2. Check the status code of the response:

    >>> response.status_code
    200
    

    Status code 200 means that the platform has authenticated the client and issued the 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 status code means that an error has occurred. For the details, refer to “Status and error codes”.

  3. 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'}
    
  4. 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}/stored-files', headers=auth)

Now, you are all set with the access to the Notary API.

Full code example

 1#!/usr/bin/env python3
 2
 3import requests  # Will be used for sending requests to the API.
 4import hashlib   # Will be used for calculating hash values.
 5import os.path   # Will be used for path-related operations.
 6import pprint    # Will be used for formatting the output of JSON objects received in API responses.
 7import json      # Will be used for converting dictionaries into JSON text
 8
 9# Define variables named "LOGIN" and "PASSWORD" and then assign them with your account credentials
10LOGIN = '<your login>'        # Change login here
11PASSWORD = '<your password>'  # Change password here
12
13# Define a variable named "cloud_url" and then assign it with the URL of the cloud platform
14cloud_url = 'https://cloud.acronis.com'
15
16# Fetch the URL of the data center where your account is located by sending a GET request to the "/api/1/accounts" endpoint
17response = requests.get(
18    f'{cloud_url}/api/1/accounts',
19    params={'login': LOGIN}
20)
21response.raise_for_status()
22
23# Convert the JSON text that the response body contains to a dictionary and store the data center URL
24# in a variable that will be used in further requests
25server_url = response.json()['server_url']
26
27# Define a variable named "account_creds", and then assign the username and password to this variable
28account_creds = {
29    'username': LOGIN,
30    'password': PASSWORD
31}
32
33# Generate a token by sending a POST request to the "/api/2/idp/token" with your account credentials to the cloud platform
34response = requests.post(
35    f'{server_url}/api/2/idp/token',
36    headers={'Content-Type': 'application/x-www-form-urlencoded'},
37    data={'grant_type': 'password', **account_creds}
38)
39response.raise_for_status()
40
41# Convert the JSON text that the response body contains to a dictionary and then assign it to a variable named "token_info"
42token_info = response.json()
43
44# Define a variable named "auth" and then assign it with a dictionary with "Authorization" key containing
45# token string formatted as "Bearer <access_token>"
46auth = {
47    'Authorization': 'Bearer ' + token_info['access_token']
48}
49
50# Define a variable named "base_url", and then assign the API base URL using the data center URL
51# to this variable
52base_url = f'{server_url}/api/notary/v2'