Developer Blog - API Updates in Preservica 7.6

For a summary of all our APIs, you can use the documentation index page.

Preservica 7.6 is a Long Term Support (LTS) release, for our cloud hosted customers, and will also be made available to on-premise customers.

Deprecation notice: /api/accesstoken/acquire-external

This endpoint allows you to get an access token for any user on your tenant, via a shared secret. It was originally the recommended approach for integrating Preservica APIs into a third party portal or website when using an external authentication provider; for example, we use it for Universal Access when you configure it to use SAML.

There are a few problems with this API. The most serious is that if the shared key is leaked, it can be used to log in as any user on the tenant, making this shared secret as important to store securely as things like admin or server credentials. This also means it can only be configured by a system admin, so on our cloud systems it required you to contact our support team. It's also not a very convenient way to manage integration, as users must also be added to Preservica's secondary credential store in order to receive roles, meaning you still have to manage users both in the external credential store and in Preservica itself.

If you're using this endpoint, the recommended approach is:

• If you're integrating a user facing website with Preservica APIs (similar to our Portal), send the user to our login page (/auth/login?redirect={your site}). You can configure the trusted URLs in your authentication config if you need to host the site at a different location to Preservica. Configure Preservica's authentication to use SAML and set up a SAML application in your third party authentication service (e.g. Microsoft Entra) if you want to integrate with it.
• If you need to access user data from a background script, create a dedicated service user with SDB_SERVICE_USER role and whichever other roles it needs, and log in to that API only user with /api/accesstoken/login. You still need to protect the credentials for this user, but the consequences of leaking them will be less severe.

I'm not aware of any of you using this API directly but if you are, and not for either of the scenarios above, please contact us so we can help you find another approach.

We don't have a fixed date for the removal of this endpoint yet.

APIs No Longer Provisional

As part of finalising an LTS release, we have removed the Provisional status from all of our public APIs. We're confident that we won't be making major breaking changes. Remember that most of our APIs are versioned so you can protect yourself from changes by using the versioned endpoints if you wish.

Functional Permissions

User sessions include functional permissions that control access to different aspects of system functionality, for example whether you can configure security tags or start ingests. You may have seen the documentation reflect this already, with wording like: "Requires authentication. Requires TenantManager permission, via a role: ROLE_SDB_ADMIN_USER, ROLE_SDB_MANAGER_USER". Functional permissions are allocated to roles, but unlike content access permissions, aren't linked to security tags.

In 7.6, APIs which return user details (/api/user/details and various login type endpoints on the Authentication API) now include functional permissions that you have, e.g.

{
 "success": true,
 "user": "manager",
 ...
 "functionalPermissions": [
 "TenantManager",
 "Ingest",
 "DataManagement",
 "Access",
 "Transform",
 "DeleteSubmission",
 "UploadContent",
 "DownloadUploadWizard",
 "ApplicationAccess"
 ]
}

You can use these permissions to control the visibility of UI controls or to decide what actions you will attempt to perform in a script. In particular the ApplicationAccess permission indicates that you should be able to use a UI; if you are creating a custom UI for Preservica you should require that user sessions have that permission.

Authentication API

Before you use any of our other APIs, you'll need to get an access token through this one, via /api/accesstoken/login or one of the related endpoints.

Changes since 7.5

• As mentioned above, POST to /acquire-external is deprecated and you should use an alternative mechanism.
• Responses from login requests when you pass includeUserDetails=true now include functional permissions.

Content API

This API provides a read only view of your archive, search capabilities, asset download and information about entities suitable for a public access portal

Changes since 7.5

• Search type requests now permit ranged requests (similar to dates) for numeric values.

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system.

Changes since 7.5

• You can now fetch and update the name of a representation at /information-objects/representations/{specifier}/name.
• Representation metadata (e.g. from GET /information-objects/representations/{specifier}) now includes a RenderLink element if the representation is renderable, with a URL for a render iframe and text you can use in a UI control.
• Endpoints that take a representation specifier in the URL now have a wider acceptance of what that specifier can be: you can now use (i) a representation type name (e.g. Access), in which case the latest representation of that type will be used; (ii) a representation name, in which case the representation with that name will be used; or (iii) a combined type and index (e.g. Access_2).

Metadata API

This API allows you to manage the new (forms/groups) view of descriptive metadata.

Changes since 7.5

• GET /indexed-fields now takes an optional parameter bulk-editable-only, which restricts the results to only fields which can be used with bulk metadata editing. Note that the equivalent endpoint on the Content API has not been updated as this information isn't relevant to Content API consumers.

User API

This API provides access about your user sessions and profile.

Changes since 7.5

• A GET to /details now includes functional permissions.

Settings API

This API allows the retrieval of information about settings on your Preservica system.

Changes since 7.5

• There are now endpoints under /metadata-enrichment to configure metadata enrichment to happen post ingest, if it's enabled on your tenant. Metadata enrichment is currently only identification of PII. Look out for more communication about this feature in the near future!