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

#!/usr/bin/env python3

import requests  # Will be used for sending requests to the API.
import hashlib   # Will be used for calculating hash values.
import os.path   # Will be used for path-related operations.
import pprint    # Will be used for formatting the output of JSON objects received in API responses.
import json      # Will be used for converting dictionaries into JSON text

# Define variables named "LOGIN" and "PASSWORD" and then assign them with your account credentials
LOGIN = '<your login>'        # Change login here
PASSWORD = '<your password>'  # Change password here

# Define a variable named "cloud_url" and then assign it with the URL of the cloud platform
cloud_url = 'https://cloud.acronis.com'

# Fetch the URL of the data center where your account is located by sending a GET request to the "/api/1/accounts" endpoint
response = requests.get(
    f'{cloud_url}/api/1/accounts',
    params={'login': LOGIN}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and store the data center URL
# in a variable that will be used in further requests
server_url = response.json()['server_url']

# Define a variable named "account_creds", and then assign the username and password to this variable
account_creds = {
    'username': LOGIN,
    'password': PASSWORD
}

# Generate a token by sending a POST request to the "/api/2/idp/token" with your account credentials to the cloud platform
response = requests.post(
    f'{server_url}/api/2/idp/token',
    headers={'Content-Type': 'application/x-www-form-urlencoded'},
    data={'grant_type': 'password', **account_creds}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and then assign it to a variable named "token_info"
token_info = response.json()

# Define a variable named "auth" and then assign it with a dictionary with "Authorization" key containing
# token string formatted as "Bearer <access_token>"
auth = {
    'Authorization': 'Bearer ' + token_info['access_token']
}

# Define a variable named "base_url", and then assign the API base URL using the data center URL
# to this variable
base_url = f'{server_url}/api/notary/v2'