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.
The response body will include all errors:
{
"success": false,
"errors": [
"Field name can't be blank",
]
}
500 Internal Server Error
There was a problem with our server. Try again later or contact support to learn more.
Updated about 2 months ago