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:
|
Create an API Key
To create an API key:
-
In Semarchy Configuration, select API Keys in the navigation drawer.
-
In the API Keys editor, right-click in the API Keys table and select
New API Key. The Install API Key wizard opens.
-
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 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.
-
-
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. -
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 thecom.semarchy.xdm.rest.accesslog
logger.