Before you use any of our other APIs, you'll need to get an access token through this one.

In most cases that will mean submitting your user name and password to the /login endpoint. It's also a good idea to send the tenant – if you don't know what your tenant name is, log in once without it but requesting the user details, which includes it. These parameters must be passed in the post body and the format must be x-www-form-urlencoded:

username=joe.bloggs@institution.net&password=xyz&tenant=INST

The response to this (assuming your credentials are valid) will give you a JSON response containing an access token:

{
    "success": true,
    "token": "0629571d-072b-4fce-bbeb-dc83e9a8ad0c",
    "refresh-token": "08437ed2-4bd1-489a-8d20-463544b05437",
    "validFor": 15,
    "user": "joe.bloggs@institution.net"
}

You can then use the access token (in the token field) to authenticate with our other APIs, by setting the Preservica-Access-Token custom header, or a Bearer type Authorization header.

If you include the optional parameter &includeUserDetails=true then you will receive additional information including the tenant and roles, which can be useful for building a user facing application:

{
    "success": true,
    "token": "215211d4-ab86-44aa-b355-5f02433d2018",
    "refresh-token": "31eed469-f95b-4930-af55-d3c6e7ccb31b",
    "validFor": 15,
    "user": "joe.bloggs@institution.net",
    "fullName": "Joe Bloggs",
    "email": "joe.bloggs@institution.net",
    "tenant": "INST",
    "tenantValue": "686ef128f436af3d9354d18a7aaec0aa"
    "roles": [
        "ROLE_SDB_MANAGER_USER",
        "ROLE_SDB_REGISTRY_ADMIN_USER"
    ],
    "lastSuccessfulLogin": "2021-04-26T11:07:47.000+01:00"
}

If you're already logged in you can also get this information from /api/user/details.

Token Lifetime and Refresh

Newly created access tokens last for 15 minutes (this is the validFor field in the response). Before that token expires, you will need to generate a new one. You could just request a new token with credentials each time, but in a user facing scenario this means you need to request the password each time. Instead, it's better to use the refresh token with the /refresh endpoint.

Submit the current access token as the authentication, and the refresh token in the refreshToken parameter. You will receive a response similar to what you get from /login, with a new access token and new refresh token.

Note that unlike OAuth 2, you can't use a refresh token after the initial access token expires, so you can't wait for a 401 and then refresh, or have 'remember me' like functionality where you store a refresh token. You must proactively manage your token refreshes.

Cookie Based Authentication

If you are using the APIs in a context where cookies are supported, for example in a user facing browser application or using libraries that support cookies, you can request that our API saves a cookie with your access token. This cookie won't be accessible to script, making it harder to hijack or steal with a XSS attack on your site. To use the APIs in this way:

• Make your login request passing cookie=true. If you're using the /login (or temporary users, see the Admin API) endpoint, this also needs to be in the POST body.
• When you need to refresh your token, you can call /refresh with cookie=true, and no refresh token. Your access token cookie will be refreshed if necessary. This will keep your session alive, so you are responsible for ensuring your session management aligns with appropriate security policies around session timeouts.

Your script doesn't need to know about the access token at all.

Two Factor Authentication

If 2FA is enabled on a tenant, your API logins will have to perform 2FA as well. (Accounts which only have the Anonymous role are an exception, so you can serve a public anonymous portal like our UA/Portal with API logins.) If you want to use a service account for automated scripting, you should keep the credentials and the token generating key separate, otherwise you don't really have two factors! For a user facing application you should prompt the user for the second factor.

In terms of the mechanics of authenticating with 2FA:

• The request to /login (or other initial login endpoints) will return a HTTP 401 (because your authentication is not complete), the message will contain "needs.2fa", and the value will include a continuation-token.
• You should prompt the user (or generate, for a non-interactive service) the 2FA six digit token and submit it to complete-2fa endpoint. Our 2FA follows RFC4226/6328 for time based one time passwords (the same as Google Authenticator etc). Because it's time based, if you're generating a token, make sure the clock on the system is accurate.
• If you receive "needs.2fa.setup" rather than "needs.2fa", the response will also contain a secretKey. This is the authenticator key which you should save, or show to the user in a way that they can save (e.g. we use it to show a QR code that an authenticator app can save). As above, you need to generate or prompt for a valid authenticator code using this key and make a call to complete-2fa. Once you successfully call complete-2fa, the authenticator key will be saved against that user and future login requests will require it.
• The response from complete-2fa is the same as you get from login if 2FA is disabled, containing an access token that you can use as normal.
• You will also get a cookie (Preservica_2FA_{user-hash}) set. You can pass this to future /login requests to skip 2FA if you already did it within the persistence time. This is most useful if you are using the API to back a user facing application. You can safely send all these cookies with different hashes to the API, only the one for the right user will be inspected.
• Failures: If a user enters an incorrect code too many (3) times, their account will be locked and a manager will need to unlock them from the 2FA configuration page. The number of failures and maximum attempts will be returned in the failure response.

There are more details in this blog post by Andy from our CX team.

Logging Out

Your access token will expire after 15 minutes if you don't refresh it. For many use cases, this is good enough. But if you want to force a session to close, you can call close-current, or revoke.

External Authentication

If you want to support SAML in a user facing portal, don't use this API to do it – instead, you should forward your users to /auth/login (or /auth/login/{tenant-value}) and allow our auth service to manage the SAML interaction. A successful authentication loop there will set the access-token cookie which can be used to authenticate with our APIs.

You can use acquire-external to assert a user identity when you don't have credentials, for example if you are managing an external authentication integration that Preservica doesn't support. You need to share a secret between Preservica (in system properties) and your integration, and it is extremely important to keep this secret secure as it enables logging in as any user on your tenant.

This API provides a read only view of your archive, search capabilities, asset download and information about entities suitable for a public access portal (in fact it backs our Universal Access portal).

Endpoints on this API typically take query parameters or a form encoded POST body, and return JSON.

Searching

Many requests on this API (obvious ones like /search and /search-within, but also those returning a list of entities at /top-level-list and /object-children) do a search against Preservica's search index. The form of all of these endpoints is similar, and the complexity is in creating the q parameter which defines the query. The Swagger doc for each of these requests describes how to set up the q parameter.

You need to set the metadata query parameter, and also put the metadata fields in the q parameter's fields section, if you want metadata in the response. These fields are the custom indexer short name, e.g. xip.created or oai_dc.subject.

Search queries all permit you to send a POST request so the q parameter can be sent in the POST body, as it can be too long or complex to realistically put in a GET query.

The result from these endpoints gives you the objects that matched the search, and other information as requested in the query, e.g.:

{
  "success" : true,
  "version" : 1,
  "value" : {
    "objectIds" : [ "sdb:SO|866d4c6e-ee51-467a-b7a3-e4b65709cf95", "sdb:IO|a9e1cae8-ea06-4157-8dd4-82d0525b031c" ],
    "totalHits" : 2,
    "simpleChildSearch" : false,
    "metadata" : [ [ {
      "name" : "xip.title",
      "value" : "example so"
    } ], [ {
      "name" : "xip.title",
      "value" : "example io"
    } ] ]
  }
}

The list of object IDs will be the same length as the metadata list, and you can merge those two lists together to get summary information you can display in the search result for each entity. You can also use this information together with the Entity API to retrieve more details about an object. Facet data will also be returned for each facet you request.

Search results can also be generated as a CSV using the /search-export endpoint.

Object Details

The /object-details endpoint takes an object ID (with the sdb:IO or :SO prefix) and gives you back metadata you can use to display the entity. The form of the response to this will be something like:

{
    "success": true,
    "version": 1,
    "value": {
        "id": "sdb:io|eb660290-fda0-40ae-a878-e82af22ce636",
        "name": "Image of Oxford city centre",
        "properties": [
            {
                "name": "cmis:objectId",
                "value": "sdb:io|eb660290-fda0-40ae-a878-e82af22ce636"
            },
            {
                "name": "cmis:name",
                "value": "Image of Oxford city centre"
            },
			// ...
        ],
        "metadata": {
            "title": "Image of Oxford city centre",
            "description": "A photo of High Street, Oxford",
            "groupOrItem" : [ {
              "title" : "DC Metadata",
              "groupOrItem" : [ {
                "name" : "subject",
                "value" : "The city of Oxford",
                "type" : "oai_dc.subject"
              }, {
                "name" : "publisher",
                "value" : "Joe Bloggs",
                "type" : "oai_dc.publisher"
              } ]
            } ]
        },
        "links": [
            {
                "rel": "render",
                "href": "https://eu.preservica.com/Render/render/external?entity=IO&entityRef=eb660290-fda0-40ae-a878-e82af22ce636",
                "type": "View Image"
            }
        ]
    }
}

The metadata that is returned is a result of running the CMIS transform for relevant descriptive metadata fragments (in this case I have set up an OAI DC to CMIS transform). There is an extensive set of cmis: and sdbcmis: properties which you can inspect. Possibly useful are:

• sdbcmis:parentId and sdbcmis:parentName, if you are accessing an object without that context and you want to show it.
• sdbcmis:downloadable to see if the current user has permission to download the item. If they do, cmis:contentStreamLength and cmis:contentStreamMimeType will tell you more about the content and cmis:contentStreamFileName is a potential downloadable name.

Content

You can retrieve content for an asset through the /download endpoint. This will fetch the displayable content for the asset (the same thing that is rendered in UA when you visit the asset). It accepts ranged requests so you can use it to back e.g. a video player. If you want more specific bits of content inside the asset, use the Entity API.

This API is for getting information from the Preservica Registry, and updating it if you have institution specific preservation needs. Access to read the Registry is generally open. Typical use cases involve reading information off entities (generation and representation formats) and reading them from /file-formats or /representation-formats to display names to a user, or reading a list of migration rules from /business-rules to offer migration options to a user.

You need Registry Admin role to make any updates (which, on our hosted systems, is only available to Preservica staff). See this blog post on PAR for more information about PAR and how to use this API. Note that this API is on the Registry webapp (on the application server), not on the API webapp.

The Process Monitor API lets you see information about ongoing processes, messages associated with them, and a day-by-day history of long running processes (large ingests). It is most useful for tracking OPEX ingests, but normal ingests also create a Process which you can watch with this API. You can also see some background system actions (in particular, automatic recharacterisation or migration policy application) and other user triggered actions (like Move operations) in this data. This API exposes the same information available through the Monitor webapp, or the Notifications panel on SDB and Explorer, if you have those enabled.

If a process runs over multiple days and is updating the size values as it does so, you can get a daily history of those numbers from the timeseries endpoint.

Completed processes will be removed from this data 90 days after completion.

This API allows you to manage Invitations and Submissions for our External Submissions process programmatically. See the UI-driven guide for the feature, as the API covers the same use cases.

The Report API allows you to retrieve and run reports. Like the Entity API (see Long Running Processes), it has a progress endpoint to allow you to track long running reports, and an /actions/reports endpoint to see running or completed reports.

Note that this API is about generation of the document style reports (normally PDF), i.e. what you get from the Reports item in the main application. If you want data to show in an interactive way or to analyse outside Preservica, you might want the Analytics API.

This API provides security information visible for the current user. This is a list of tags that the current user can see, and what permissions they have on those tags. Use this information in conjunction with security descriptor information on entities to decide what actions to show a user, or to determine which tags should be offered when creating entities etc.

Security configuration is done through the /security section of the Admin API.

You can use this API to discover your storage quota limit. This is currently only relevant in the context of Preservica Starter.

This API allows you to get information about your own user account after logging in (for example to display a Profile page in a UI), and to manage your profile and sessions. User management is done through the /users section of the Admin API.

A GET to /details will return user information like that in a login response. You can use this if you've used external authentication or asked the user to log in manually, to retrieve information to display about the user (e.g. a name) and adjust UI choices based on the user's roles,

This XML API lets you control most aspects of workflow management, including starting, stopping and terminating workflows, submitting results to tasks which normally require human interaction, and uploading definitions and contexts. This API is described in the SDK: Customisation API document as well as the individual endpoint documentation.

Details of parameters to workflow steps are only available to admin users (on cloud hosted systems, that means Preservica staff) because this can include sensitive information about the system.

Note that requests to this API go to the /sdb webapp on the application server, not the API server as most of the other APIs. This is because workflows are managed in that webapp.

We support a limited view of what's in Preservica through some open standards. Use these APIs if you need to integrate with a system which uses these protocols. If you have a free choice, we recommend you use the Entity or Content API to access this information.

OAI-PMH

OAI-PMH is a standard protocol through which archival systems can exchange information. Preservica exposes data as an OAI-PMH data provider through the /OAI-PMH route. This API is described in the SDK: Content API document.

The main use of OAI-PMH is to list recently changed records. If you aren't integrating with an OAI-PMH consumer, consider using /entities/updated-since on the Entity API.

CMIS

CMIS is a standard protocol through with content management systems can exchange information. Preservica exposes a limited subset of data through a read only CMIS 1.1 endpoint at /api/cmis/atom. (You can't use CMIS to create or update entities in Preservica.) The information available through CMIS is similar to that exposed by the Content API endpoints for top level entity listing, object details, searches and object children. Like the Content API, the information returned in the CMIS Metadata extension is generated from the relevant descriptive metadata fragments through their CMIS transform (e.g. a MODS to CMIS transform if you have MODS metadata).

The Content API is more widely used and more robust so consider using that if you aren't integrating with a CMIS consumer.