Before getting started, please carefully read the following to make sure you fulfill all requirements for the integration to work:

1. Set up an API user

For allowing access to the Eploy API, it is necessary to create a special user account that will have access to the API.

In Eploy, go to Admin > Users. Here you will see all Users you have the ability to manage.

An API User is a standard user within the system. However, there are certain stipulations to users that can be allocated to an API Key, i.e.

Only one ‘Role’ can be associated (users with more than one role cannot be allocated to an API key).
At least one IP range configured in the ‘Restricted IP Access’ section (without this, your API Key will be unable to connect).

Click New > User to create a new Standard User in the system.

On this form, you first need to complete the following:

• “User Display Name”: Use a unique name that describes the user, e.g. “API User”.
• “User Name”: Use a unique name for your API user.
• “Roles”: You need to assign one Role to the user (only one Role may be assigned to an API User). Please note that the role you choose will affect the permissions allocated to your API User and therefore which permissions, fields, and data can be accessed by the API when you allocate this API User to an API Key. You can design a Role specifically for the API User if you need to restrict certain aspects of the system from being accessible via the API (please see the other articles available in the Standard (Core System) Users section for more help on setting up Roles & Permissions).
• “System Email Address” / “Email Display Name” / “Your Direct / Internal Email Address”: These all need to be set on the API User, but you should use a generic email address that is not used by any real users. It does not necessarily need to be a working email address, because no one should need to see emails delivered to it, so something like “noreply@yourcompany.com” would suffice.

Before saving the user, we need to set up IP restrictions, to allow API access on behalf of this new user.

2. Assign IP Restrictions

Now that you have created the user record, for the user to be able to access the API, you need to specify at least one IP range in the ‘Restricted IP Access’ section.

Click the "Add" button in the Restricted IP Access section to add a new IP range.

Enter 0.0.0.0/0 and press "Save", to allow access from any IPv4 source.

Press the "Add" button a second time to add a new IP range and enter ::/0, to allow access from any IPv6 source. Then press "Save"

Now you can press the "Save" button at the bottom of the page to create and save the API user.

 

2. Take note of your subdomain

The subdomain is the first part of the URL you use to log in to your Eploy account, the word right before .eploy.net, for example, if your login URL is https://acme.eploy.net your subdomain is the word "acme".

Now enter the subdomain in the connection flow and press "Continue".

3. Go to the API Keys section in eploy

After logging in to your eploy account, go to Admin > Security Settings > API Keys. 

4. Open the "Create API Key" dialog

Once in the "API Keys" section of the admin panel, click the New > REST API menu link.

5. Create API Key

In the "Create API Key" page, enter a name for your API Key, then select the user that was created in the first step and press "Save".

6. Add API Permissions

The next step is to add the permissions you want for the ISU. You can find the list of permissions needed in the connection flow.

For each permission, repeat the following process:

a. Press the "Add" button under "API Permissions"

b. Select a permission type in the "API" dialog

c. Check the permission boxes as required, and then save

7. Review permissions and save

After all the permissions have been added to the API key, you can view them all and double check that they match to what is listed in the connection flow:

To save the API key and commit this changes, press the save button:

8. Obtain Client ID and Client Secret

Press the "Generate New Client ID & Secret" button

You should see a new dialog pop up. Press the "Show" link and copy the values of "Client ID" and "Client Secret" into the connection flow:

Then press "Set up integration".

 

 

Troubleshooting

If during the connection flow, you receive an error about missing permissions, despite having configured your key correctly, it is likely that the user used to create the key does not have the appropriate permissions. The user owning the key must have at least the same permissions (or more) as the key for it to work correctly.