Setting Up An API Key

Prerequisites

To set up an API Key, first, you need to have configured an API User. Please consult the guide Eploy RESTful API: Setting Up An API User for instructions on how to do this.

In order to configure an API Key, you need to have the ‘Admin – System /Security’ > ‘Configure API Keys’ Permissions assigned to your User Role. If your Role has a specific Permission Group assigned to it, please ensure that these permissions have been enabled (please see the other articles available in the Standard (Core System) Users section for more help on setting up Roles and Permissions).

Process

In Eploy, go to Admin > Security Settings > API Keys to access the API Keys section.

At the top of the screen, you can see which API Package you have available in your system (this determines how many API calls you can make per day). You can also see statistics on how many API calls have been made today, and the average daily usage during this month and the previous month. Please note that the daily API usage limit is shared across all API keys in your system. If you think the integration you are preparing to configure is likely to take you over the current daily limit, consult with your Eploy Account Manager about what other packages are available.

Below these statistics, you can see any API Keys that have already been configured. You can click into an existing API Key to make changes, but please be cautious as changing an existing key may affect any live integrations you may have.

To create a new REST API Key, click ‘New’ > ‘REST API’.

On this screen, you will need to set the following fields:

• “Title”: Enter a name for your API Key. The name should describe the integration the key is going to be used for, so that future users know its purpose.
• “Run As User”: Select an API User for your API Key to use. This is the user that any API activity carried out using your key will be attributed to, and therefore should not be an actual Eploy user. If you haven’t already configured an API User, please consult the guide Eploy RESTful API: Setting Up An API User for instructions on how to do this.

Once you have set both of these fields, click ‘Save’ to create the API Key.

You will now be presented with a screen showing the details of your API Key, including the Client ID. The Client Secret can be revealed by clicking ‘SHOW’. Please note that once you save the API Key, the Client Secret can no longer be accessed, therefore please note your Client ID and Client Secret before you navigate away from this record (you will be able to regenerate the Client ID & Secret if necessary).

Note: If you see the following warning message, this means that the API User you have configured does not have any IP Restrictions set, and therefore you will not be able to access the API. Please revisit the Eploy RESTful API: Setting Up An API User guide and follow the instructions in the ‘Assign IP Restrictions’ section.

Finally, you need to assign API Permissions to your API Key. To do this:

• Click the ‘Add’ button in the API Permissions section
• Select the API endpoints you wish to grant permission to
• Tick the relevant boxes to assign ‘View’, ‘Insert’, Update’ and ‘Delete’ permissions (note: not all API’s allow all of these permissions, so some will have a fixed value of ‘No’.
• Click Save
• Repeat this process for each API you need the key to be able to access.

Once you have assigned all the necessary API Permissions, click ‘Save’ to save your API Key.

Note: you can revisit your API Key later to modify it, including renaming your key, generating a new Client ID & Secret, altering the API User or modifying the API Permissions. You can also click ‘View Logs’ at the bottom of the key to view the Security Audit Log for any API activity that has taken place using this key (you will need to have the ‘Admin – System /Security’ > ‘View Security Audit Log’ Permissions assigned to your User Role in order to access this).