Manage API Keys

API Keys are used by applications to authenticate and use the Semarchy xDM REST APIs.

API Keys are defined at platform-level, and have the following characteristics:

  • They have a set of Roles whose privileges apply in API calls.

  • They have a Default User Name used when the API requires one.

  • They may be de-activated temporarily or permanently.

  • They have an optional Expiry Date.

  • Calls made with a key may be restricted to originate from specific IP addresses or IP address ranges.

Make sure to select for an API key the right roles to interact with the data, since data model privilege grants apply:

  • The API key should have a role attached to a model privilege grant with the Grant access to the Integration API option selected in order to interact with data stored in the given model.

  • In order to set a different user when interacting with data, the API key should have a role attached to a model privilege grant with the Allow Publishing as user in API option selected.

Create an API Key

To create an API key:

  1. In Semarchy Configuration, select API Keys in the navigation drawer.

  2. In the API Keys editor, right-click in the API Keys table and select ApiKey New API Key. The Install API Key wizard opens.

  3. Enter the following information:

    • Label: User-friendly label for the API Key. Modifying this label is optional.

    • Default User Name: Default user name used for operations made with this API Key.

    • Roles: Click the edit expression button Edit button to select the roles to grant to this API key.

    • Expiry Date: Optionally select an expiry date for the key. By default, a key has no expiry date and never expires.

    • Origin IP Addresses or Ranges: Enter a comma-separated list IP addresses (e.g.: 192.168.0.1) or ranges (e.g.: 172.16.0.0/12). Only addresses listed are allowed to connect using the key. Leave this field empty to allow all addresses.

  4. Click FINISH. The Save API Key dialog opens and displays the generated API Key.
    Copy this key to a safe place, or click the link to save a file containing the key value.

  5. Make sure that you have saved the key and then click OK.

The key is created. You can use it to connect the REST API.

After creating an API Key, from the API Keys editor, you can:

  • Edit a key, for example, to change its roles or set its expiry date.

  • Delete a key.

  • Expire a key (Right-click then Expire Now), which sets the expiry date to the current date and disables the key.

  • Re-enable a key by editing it, then selecting an expiry date in the future, or using the Clear button in the Expiry Date selection dialog to make the key active with no expiry date.

  • Review a key last usage in the Last Interaction section of the key editor.
    To trace the detailed usage of API keys, use the com.semarchy.xdm.rest.accesslog logger.

Use an API Key

To use an API key:

To use this API key in a REST API call, set an HTTP header called API-Key, containing the API key previously created. For example:

API-Key:rXXTAYe.X2jMCtbNr652xu7x91kB7cSYJKCt3SFKohj