• API Reference
  • Access Token API

Access Token API

The API web application provides an API to request access tokens, which can then be used to submit requests to other APIs within Preservica.

To request a token, send a POST request to /api/accesstoken/login, with the user name, tenancy and password as form parameters in the content (e.g. username=accessuser&password=secret&tenant=TENANT_ID). If the credentials are correct, you will receive a JSON response similar to:

{ "success": true, "user": "access-user", "token": "46e4402d-7309-4bec-a913-
e97f9fa386be", "refresh-token": "3b5c4c11-8df9-439c-9a7e-c0875461079b",
"validFor": 15}

If a session could not be created, the response will be a HTTP 401 (Unauthorised), and the reason will be available in a message parameter in the JSON response. A successful token is valid for 15 minutes.

The response includes a refresh token that can be used to request a new access token by sending a POST request to /api/accesstoken/refresh with the refresh token as a form parameter in the content (e.g. refreshToken=3b5c4c11-8df9-439c-9a7e-c0875461079b). If successful the response will be similar to a login request. This request is authenticated so must include the HTTP header Preservica-Access-Token header. The refresh token is valid for the same period as the access token and can only be used once.

A token can also be generated through the externally authenticated acquisition API. This allows a trusted external application to acquire Preservica access rights without being authenticated by Preservica. Trusted applications must verify a user’s identity, and you should only configure this API if you wish to use it, and only open it to access from known trusted sources (such as your Universal Access deployment). The external acquisition API is at /api/accesstoken/acquire-external and takes a request of the form username=accessuser&tenant=TENANT1×tamp=1486725429&hash=5fc9da1b5239d064fc3abf94b14cc00e313d589b.

The timestamp is a Unix timestamp, e.g. generated from PHP’s time() function. The hash is generated using the tenant’s shared secret (configured in the tenant specific system property external.auth.key) as: sha1("preservica-external-auth" + timestamp + username + shared_secret).

To use an access token with an API that supports it (the CMIS API and Content API), set the HTTP header Preservica-Access-Token to the token string.

You can find Swagger UI for the authentication API at https://demo.preservica.com/api/accesstoken/documentation.html.

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.