Authentication

The PACE API uses an API key method of authenticating incoming requests. Only a PACE administrator with appropriate permissions can access the Administration area of PACE to generate a key. In the administration menu, select System configuration this will navigate to the System settings page where you can select the item API settings.

API settings

This page allows the administrator to either create or revoke API keys used to access the PACE API. It also displays the customer identifier which is unique to your system. Both the key and the customer identifier must be included with all API requests.

Generating keys

Click on Create API key to generate a key. The key is a completely unique, secure key which acts as a password for your client access. When the key is generated, it will be displayed in plain text this time only.

Important

You must copy the key and save it for use in the client requests. It will not be shown again. Cardinus technical support cannot recover this key so a new key must be generated if the old key is lost.

Details of the key now show on the API settings page, and it is immediately ready for use in the client application. You can return to this page at any time to view the last access date of any clients using the key.

If you require a second key, you can repeat this process by clicking Create API key again. There is a limit of two API keys, after which you must revoke keys before you can generate more.

Revoking keys

API keys can be revoked when necessary. Revoking keys may be due to scheduled key rotation, or if you believe a key has been compromised in some way. Revoking allows you to instantly disable an API key so any access attempted when using that key is prevented. Click on Revoke API key next to the key you want to disable. This will prompt you to confirm this decision due to the disruption it could cause. Click Yes to confirm the revocation, or No to cancel any changes. The API settings page will be updated to show any remaining active keys.

Using the key

Once you have set up the keys you need, you must attach it to any requests. The key must be included in the request header using the header key x-api-key. Use the key exactly as copied when the key was generated.

You must also include a header value for the customer identifier using the header name x-api-id This value can be found on the API settings page on the details panel on the right of the page.

This table shows the authentication headers set up for a PACE API request. x-api-key and x-api-id are always required.

Key	Example value	Description
x-api-key	NX88yV6B0QZpFf0358H6zecpD-4-DBAJJCUFzEHjRMw	The value generated when creating an API key.
x-api-id	75365663-f930-40b3-b250-c7d340235f2d	The unique customer id for the PACE system.