Getting Started

Getting started with Preservica access tokens

Andy Dean

April 30th, 2020

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:

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:

Host =
Username =
Password = xxxxxxxxxxxxxx

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 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 script in the same directory as those scripts that require a valid token allows the script to be referenced (or imported) and used when required.

For example:

My accesstoken script is called “” 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 script (for example) includes the following import statement

  • from preservicatoken import securitytoken

I can now call the securitytoken function within my “” script and request a token whenever the “” 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.

Examples of the config.ini file, the “” and “” can be found at Preservica’s Github repository here.

More updates from Preservica

Getting Started

Custom Reporting via the Preservica Content API

Preservica provides a REST API to allow users to query the underlying search engine. In this article we will show how CSV documents can be returned by the API.

James Carr

November 29th, 2021

Getting Started

Using OPEX and PAX for Ingesting Content

Preservica has developed the concept of an OPEX (Open Preservation Exchange) package, a collection of files and folders with optional metadata, as a way to organise content into an easy to understand format for transfer into or out of a digital preservation system. Although we have created it, we hope suppliers of digital content to be preserved, and other digital preservation systems, will use it due to its simplicity.

Richard Smith

January 28th, 2021

Getting Started

Using the PAR API to create Custom Migrations

Since the release of v6, Preservation Actions within Preservica have been defined and controlled using a PAR (Preservation Action Registries) data model. To facilitate this, Preservica’s registry also exposes a PAR API to allow a full range of CRUD operations on this data. This API also makes it possible to write new migration actions using Preservica’s existing toolset, for example, to introduce re-scaling to your image/video migrations, or to get different output formats altogether. In this article, we will introduce the key concepts in this data model, explain how Preservica uses and interpret them, and introduce the API calls required to create your own custom actions. We will do this by a worked example, using ImageMagick to create a custom “re-size migration” for images.

Jack O'Sullivan

August 11th, 2020

Getting Started

Using Python with the Preservica Entity APIs (Part 3)

In this article we will be looking at API calls which create and update entities within the repository, some calls to add and update descriptive metadata and we will also look at the use of external identifiers which are useful if you want to synchronise external metadata sources to Preservica.

James Carr

June 11th, 2020

Preservica on Github

Open API library and latest developments on GitHub

Visit the Preservica GitHub page for our extensive API library, sample code, our latest open developments and more.

Protecting the world’s digital memory

The world's cultural, economic, social and political memory is at risk. Preservica's mission is to protect it.