Manage API keys

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

API keys are defined at the platform level and have the following characteristics:

  • They have a set of roles with associated privileges that apply to API calls.

  • They have a default username used when required by the API.

  • They may be temporarily or permanently deactivated.

  • 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 appropriate roles for an API key to effectively interact with data, as data model privilege grants apply. Consider the following:

  • 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 within the given model.

  • To enable interaction with data as a different user, 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 the navigation drawer of the Configuration interface, select API Keys.

  2. In the API Keys editor, right-click in the API Keys table and select API key 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 username used for operations made with this API key.

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

    • (Optional) Expiry Date: 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 of 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.

  5. Copy this key to a safe place, or click the link to save a file containing the key value.

    Make sure to take note of the key or save it for future reference.

  6. Click OK.
    The key is created and ready to connect to the REST API.

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

  • Edit a key to adjust its roles or update its expiry date.

  • Delete a key.

  • Expire a key by setting its expiry date to the current date and disabling it (achieved by right-clicking and selecting Expire Now).

  • Re-enable a key by editing it and selecting a future expiry date, or utilizing the Clear button in the Expiry Date selection dialog to activate the key indefinitely.

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

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.

Example
API-Key:rXXTAYe.X2jMCtbNr652xu7x91kB7cSYJKCt3SFKohj