Getting started with access tokens

Preservica maintains a number of API end points that allow third party systems and external processes to be used to automate such tasks as searching, ingesting and exporting content, as well as updating metadata in Preservica, to name but a few.

If you’d like to know more about the various APIs supported by Preservica, our v6 APIs are published at:

https://demo.preservica.com/api/accesstoken/documentation.html

https://demo.preservica.com/api/content/documentation.html

https://demo.preservica.com/api/entity/documentation.html

All API requests made to a Preservica solution require the passing of either valid Preservica account credentials, or a valid “access token”. In most cases using an access token is more efficient, as well as secure, and makes sense where multiple API calls are being made to a system. Naturally, the first access token request send to the Preservica accesstoken API does require the passing of a valid username and password, which should only ever be sent via an https request so that the credentials are encrypted in transit.

This blog describes a simple scenario for using Preservica’s access token along with two scripts, and one or more config files. My examples use Python3 however you can achieve similar results using a variety of alternative scripting languages of course.

Firstly, if you are using multiple scripts or you are targeting more than one Preservica environment (production and test environments for example) then having to continually update your scripts with credentials specific to the system you’re accessing is frustrating. Instead consider using a .ini file for each system you want to interact with, so that the file can be read by any of the scripts you create. In python3 the “configparser” module is useful for reading in specific values from .ini files.

My example .ini file is below:

[DEFAULT]
URL = https://ahost.preservica.com/api/accesstoken/login
Host = ahost.preservica.com
Username = a.user@preservica.com
Password = xxxxxxxxxxxxxx

Accesstoken.py

My example accesstoken script includes two functions, the first checks for the existence of, and then reads from a “token.file”, which may have been saved locally by the accestoken.py script sometime previously.

If the “token.file” exists, a data time value and a token value are read by the accesstoken script. Based on the date time value, if the token previously written to the “token.file” is still valid then the script will use this value.

If however the token is no longer valid, or indeed the “token.file” does not exist (i.e. hasn’t previously been written) then a new token is requested by the second function within the accesstoken script.

The second function reads user account and host credentials from the config.ini file, which are then used to construct a suitable POST request to the Preservica accesstoken API, using the python “requests” library, as below:

payload = 'username=' + usernameval + '&password=' + passwordval
headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
response = requests.request("POST", url, headers=headers, data=payload)

If a new token is successfully returned by the Preservica access token API the token value is extracted from the http response and written to a new or updated “token.file” along with the date time value, for later use.

Placing the accesstoken.py script in the same directory as those scripts that require a valid token allows the accesstoken.py script to be referenced (or imported) and used when required.

For example:

My accesstoken script is called “preservicatoken.py” and contains two functions

def securitytoken (used to check for an existing token in the ini file)
def newtoken (used to request a new token)

My simple_search.py script (for example) includes the following import statement

from preservicatoken import securitytoken

I can now call the securitytoken function within my “simple_search.py” script and request a token whenever the “simple_search.py” script is run.

My other scripts are similarly configured so that I have a consistent method for acquiring a Preservica access token, either from a local” token.file” or from the Preservica server.

If your scripts are designed to target more than one system you can read in the appropriate config.ini file at run time. Naming your .ini files appropriately (one for each system) and making sure that the resulting token.file is also suitably named will minimise confusion. As below, I have three .ini files defined, along with very clearly named token.files.