This article explains how to generate and manage (update, disable, re-enable and remove) Application Programming Interface (API) credentials for personnel data in Personio.
Recruiting API credentials are system-generated and are not managed by administrators. For information about Recruiting API credentials, read Recruiting APIs.
What are API Credentials in Personio?
API credentials allow data to be exchanged between Personio and another service or tool through an integration (for example, Greenhouse). You need to enter API credentials when activating an integration.
API credentials help to safeguard the communication between applications and avoid unauthorized access, which can lead to data breaches. For data security reasons, it is recommended that you generate new API credentials for each integration.
Generate API Credentials
- Go to Settings > INTEGRATIONS > API credentials.
- Click on the Generate new credential button on the top right of the screen.
- In the Add new credential sidebar that appears, enter a meaningful name (for example, Greenhouse Integration API Credentials) for the API credentials into the Name field. This name will be important if you need to re-access or remove the credentials.
- Select the relevant integration from the Integration drop-down menu.
Note: Selecting an integration does not automatically set up an integration.
- The recommended permission access level for the Employees endpoint will be preselected and can be adjusted via the Read or Write permission checkboxes. Note: If you select Write when adding an integration, the integration that is to be added will be permitted to create and update data in Personio.
- The recommended permission access level for the Absences and Attendances endpoints will be preselected, and can be adjusted via the Read or Write checkboxes.
Note: It is not possible to select the data that should be transferred from Personio via the Absences and Attendances endpoints. For more information, see Getting Started with the Personio API.
- The recommended permission access level for the Documents endpoint will be preselected, and can be adjusted via the Read and Write checkboxes. The Documents endpoint allows the upload of documents to Personio. It does not allow the credential holder to retrieve documents from a Personio account. Note: The Documents endpoint requires Read permission to retrieve the Document Category ID which is needed to push documents to Personio via the Write permission.
- The relevant attributes (for example, Name, Email and Department) that should be transferred from Personio to the integration via the Employees API will be preselected in the Readable employee attributes drop-down menu. If necessary, you can adjust the access permissions via the checkboxes in the Readable employee attributes drop-down menu. For more information about the access permission level that needs to be assigned for a specific integration, read Integrations.
- To generate the API credentials (client ID and secret credentials), click on the Generate new credential button. A message will display confirming that the credentials have been created.
Note You will need the client ID and secret credentials to activate the relevant integration. For more information on activating an integration, please refer to Personio Marketplace. Your secret credentials can be used to access account data and should be treated the same as a password. Keep your credentials confidential. Never share them with third parties.
Manage API Credentials
Update API Credentials
Follow the steps below if you want to update the name of the API credentials, the Readable Employee attributes for the employee API or the permission access level for the Absences and Attendances APIs. API credentials (client ID and secret credentials) cannot be updated.
- Go to Settings > INTEGRATIONS > API credentials and click on the relevant integration (for example, Workable).
- In the Integration sidebar that appears, make the required updates.
- Click on the Save button to implement the updates.
Disable API Credentials
Follow the steps below if you temporarily want to disable API credentials from working and want to be able to re-enable them to work again. Alternatively, you can remove API credentials if you want to delete the credentials permanently.
When API credentials are disabled, any exchange of data between Personio and an integration temporarily ceases and only recommences if the API credentials are re-enabled.
- Go to Settings > INTEGRATIONS > API credentials. All API credential details (including the API credential name, the integration name, and the status of the API credentials) are displayed on the API credentials screen.
- To change the status of API credentials to Disabled, toggle the toggle-switch beside the relevant API credentials (for example, Greenhouse) to Off. The credentials will be disabled.
Re-enable API Credentials
Follow the steps below if you want to re-enable API credentials that have been temporarily disabled from working, and you want to re-enable them to work again.
- Go to Settings > INTEGRATIONS > API credentials.
- To change the status to Enabled, toggle the toggle-switch to On.
The credentials will be re-enabled and the exchange of data between Personio and an integration recommences.
Remove API Credentials
Follow the steps below if you want to permanently delete and stop API credentials from working and will not need them again. Alternatively, you can disable API credentials if you only temporarily want to stop the credentials from working.
When API credentials are removed, it is not possible to re-enable the credentials and any exchanges of data between Personio and an integration permanently ceases.
- Go to Settings > INTEGRATIONS > API credentials and click on the relevant integration.
- In the Integration sidebar that appears, click on the Recycle Bin icon.
- You will be prompted to confirm that you want to remove the API credentials. Click on the Yes, remove button.
The credentials will be permanently removed.