API authentication

Generating API key

Go to Settings → Open API keys (bottom of the page) → Generate API key.

Creating a key allows users with this key to retrieve or change data in your company account via PeopleForce API. If you want to restrict users from making changes to viewing employee Compensation details you can change permission on the key to None.

For additional security, you can allow only users from particular IP addresses such as office IT computers or home PCs. You can leave the field empty if you don’t want to create such restrictions.

How to use key

To use API key you need to pass it as a part of the request.

Include the key in a header parameter called X-API-KEY.

Example: X-API-KEY: 123

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Revoking key

If you decided that you don't need the key for any reason, you can always delete it.
To delete an existing key go to Settings → Open API keys (bottom of the page) → Find your key in the list of keys and click Delete.

Key will be revoked immediately and access via API will be restricted from it.

Troubleshooting

401 Unauthorized

If you receive a response of 401 Unauthorized, please double-check that your API key was copied correctly and try again.

{
    "message": "Bad Credentials"
}

403 Forbidden

Your role doesn't have enough permission to perform this action. This usually will be only if you are restricted from receiving info about Compensations for employees.

404 Not Found

The resource could not be found. Please check that your request is referring to an existing object.

422 Unprocessable Entity

There are validation errors in some fields. Please refer to the documentation to check the required fields and validation rules.

500 Internal Server Error

There was a problem with our server. Try again later or contact support to learn more.