Management API Documentation

The Cadenza management API allows to validate, export, import, and delete repositories in an existing database repository schema, mainly to automate deployment procedures.

Operations

We use the OpenAPI specification to document all management API operations. The OpenAPI definition itself available as management-api.yaml or view it.

The API can always be called without any further configuration and cannot be deactivated.

Firewall rules can be used to block access to the API endpoints.

Session-Based Authentication

The API can be called, once a Cadenza session is established. Establishing a Cadenza session requires successful authentication against an authenticator listed in accessmanager-config.xml of the installation. Authentication is then handled via a session cookie.

Using the API with a user-interactive authenticator is not recommended and cumbersome. We strongly advise using the dedicated authentication method described below.

Api-Key Authentication

To avoid creating Cadenza sessions before using the API, use the dedicated apikey-httpheader authenticator in accessmanager-config.xml. This makes it easier to use the API in highly-automated scenarios. In short, the Api-Key authenticator requires the client to send its API key with the request and sign the request URL using a SHA256 HMAC without establishing a cookie-based Cadenza session.

Each client that should be able to authenticate needs to have an API key and an associated signature key registered in the server configuration. An additional client id serves as substitute user name, especially for purposes of direct privilege assignment (for e.g. Cadenza repositories) or audit logging.

Configuring the Api-Key Authenticator

To enable the Api-Key authenticator, the administrator has to

  • Enable the plugin AccessManager_ApiKey in plugins.xml

  • Configure the apikey-httpheader authenticator in accessmanager-config.xml

    In terms of order, the apikey-httpheader authenticator needs to be added before any interactive authenticators.

  • Configure individual clients with secrets in accessmanagerapikey-config.xml

    The secrets must be Base64 decodable strings.
Example accessmanager-config.xml
<userRegistry>
  …
  <authenticators>
    <authenticator refid="apikey-httpheader">
      <groupMapping refid="apikey-httpheader"/>
    </authenticator>
    …
  </authenticators>
  …
</userRegistry>
Example accessmanagerapikey-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<adminApiClientConfiguration>
  <clients>
    <client>
      <clientId>api-user</clientId> (1)
      <apiKey validUntil="2029-05-25">eV9rwLxYyuFs5cSPgueKYG6YLqoiP/yQgDXzehxal83FBXMZiTDCI4S1/MGcvjGv</apiKey>
      <encodedSignatureKey>LApqIO0HfD7VhOCVLMuVo/JbmTiK8lUgGD+WQMw9kyM0</encodedSignatureKey>
      <groups>
        <group>Administrator</group>
        <group>Creator</group>
      </groups>
    </client>
    <client>
      <clientId>workbook-management</clientId>
      <apiKey validUntil="2029-05-25">8qiHCivllWAKhE6/LvjM2WYtt9Km5+ZSm8wlbvW4YIFbPuWcDrPFwnJmGQuDAYZA</apiKey>
      <encodedSignatureKey>h6aSxNAVX7HdcjxMreZfgs+EdbFUTdJBhfPQ48dp+R5x</encodedSignatureKey>
      <groups>
        <group>Creator</group>
      </groups>
    </client>
  </clients>
</adminApiClientConfiguration>
1 First client with ID api-user is member of both the “Administrator” and “Creator” groups.

Each client must have its own, unique client ID, API key, and signature key, and none of them may equal any of the others. While in theory, it is possible to assign permissions on individual repositories to the client ID directly, system roles can only be assigned to groups. Therefore, a client should be assigned to at least one group to be able to receive the system privileges necessary for the operations he is expected to execute.

Full syntax can be found in the documentation for accessmanagerapikey-config.xml.

Using the Api-Key Authenticator

For each request to the API endpoint, client code has to perform the following steps to authenticate:

  • Extend the URL with a requestTimestamp parameter containing a UNIX timestamp in milliseconds, in other words, the number of milliseconds elapsed since 1970-01-01T00:00:00 ignoring leap seconds. For example: https://example.com/cadenza/public/adminapi/repositories/hK6HtUqLDbvz7rgMNxBk/runtestsuite?requestTimestamp=1718289522375

  • From the resulting URL,

    • Extract path and query string separated by a question mark. In the case of "https://example.com/cadenza/public/adminapi/repositories/hK6HtUqLDbvz7rgMNxBk/runtestsuite?requestTimestamp=1718289522375", that would result in "/cadenza/public/adminapi/repositories/hK6HtUqLDbvz7rgMNxBk/runtestsuite?requestTimestamp=1718289522375".

    • Sign this string with the signature key using the HMAC-SHA256 algorithm and encode the signature using Base64.

    • Pass the encoded signature in an X-Request-Signature header.

  • Pass the API key in an X-Api-Key header.

  • Optionally, pass the client ID in an X-Client-Id header for validation, too.

If the request is sent as part of an already-established and authenticated session, Api-Key authentication information is ignored.

Example Client Code in Python

We provide some python code examples to clarify the programmatic use of the API. All steps can be implemented in nearly every other programming language.

All scripts use the code in cadenza_api_util.py for the HMAC-based signing procedure, but execute a different operation. The last example shows how to use the authentication and signing procedure of the Management API to download data via the Embedding API.

The examples do not cover all functionality that is availabe through the Management API, see OpenAPI definition for a full overview.

API operation example script

(utility module for the HMAC-based signing, needed to execute the examples below)

cadenza_api_util.py

execute test repository test suite

cadenza_mgmt_api_runtestsuite.py

export repository

cadenza_mgmt_api_export_repo.py

import repository

cadenza_mgmt_api_import_repo.py

delete repository

cadenza_mgmt_api_delete_repo.py

download data from embedding link

cadenza_embedding_api_download_data.py