Setting Up An API User

Prerequisites

In order to set up an API User, you need to have User Admin access to your Eploy system. If you do not have the ‘Users’ option in the Admin menu, your user account has not been configured to allow access to configure Standard (core system) Users. Please consult with your Eploy administrator either to set up the API User for you or to grant you permission to do so.

If your Role is restricted to certain Permission Groups, you will need to ensure the ‘User Admin’ permissions have been selected within Admin – System / Security in at least one of your Permission Groups via Admin > Manage Roles & Permissions.

Process

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).

We also recommend having a user set up specifically for the API (i.e. not a user who is logging in to Eploy).

Create a New Standard User

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”. If you are going to be configuring integrations with multiple systems, we recommend using a separate API User for each, therefore you may want to be more descriptive and use a name that identifies which integration your user is intended for, e.g. “HR Interface API User”.
• “User Name”: Use a unique name for your API user. Please note, no-one should be using this user to log in to Eploy, therefore the Username does not need to comply with the naming conventions used for ‘actual’ users (e.g. if you use Single Sign-on, there is no need to match the username to your SSO attribute as no-one actually needs to use this user to log into Eploy)
• “Password”: A password needs to be set in order to save the record, however no-one needs to know this, therefore simply click ‘Update’, ‘Generate’ and then Save the password (there is no need to reveal the generated password or note it down).
• “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. If you are not using Single Sign On, please note that this email could be used to reset the API User password, therefore it is best to use an email address that either no one can access or that is restricted only to administrators. 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.

Once you have set all these fields, click ‘Save’ to save the user record.

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.

The value in the ‘IP Address’ section can either be a single IP address or an IP range using CIDR notation. IP addresses/ranges can either be IPV4 or IPV6. You should set any IP addresses or ranges that the integration that is going to use this API User needs access from. You can add more IP addresses/ranges by clicking the ‘Add’ button again, if necessary.

For maximum security, we recommend limiting the IP ranges only to those that you are going to be calling the API from. It is, however, possible to allow all IPV4 and/or all IPV6 ranges by including the following ranges, if necessary:

• (for all IPV4 ranges) 0.0.0.0/0
• (for all IPV6 ranges) ::/0

Click ‘Save’ once you have added all the required IP addresses/ranges. Your API User is now configured and ready to be allocated to an API Key.