This article explains how to generate and manage (update, disable, re-enable and remove) Application Programming Interface (API) credentials for personal data in Personio.
Recruiting API credentials are system-generated and are not managed by administrators. For information about Recruiting API credentials, please refer to 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 (e.g. 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 > 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 (e.g., 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 integration from the Integration drop-down menu. Note: Selecting an integration does not automatically set up an integration.
- Assign the appropriate access permission level for employee personal data by selecting the Read or Write checkboxes. If you select Write, the integration will be permitted to create and update data in Personio. For information about the permission level that needs to be assigned for a specific integration, please refer to Integrations.
- From the Readable employee attributes drop-down menu, select the relevant attributes (e.g., name, email and department) that should be transferred from Personio to the integration via the employee API.
- Assign the appropriate access permission level for the absences and attendances APIs by selecting 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 APIs. For more information, please refer to Getting Started with the Personio API.
- Click on the Generate new credential button.
The Client ID and credentials secret are generated. You will need these credentials to activate the relevant integration. For more information on activating an integration, please refer to Personio Marketplace.
Your credentials secret can be used to access account data and should be treated the same as a password. Keep your credentials secret confidential. Never share it 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 access permission level for the Absences and Attendances APIs. API credentials (Client ID and credentials secret) cannot be updated.
- Go to Settings > API credentials and click on the relevant integration (e.g. 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 want to temporarily 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 permanently delete the credentials.
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 > 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 (e.g. Greenhouse) to Off.
The credentials are 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 > 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 want to temporarily 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 > 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.
Can't find what you're looking for?
We are happy to help you! Just write us a message with your questions and we will get back to you as soon as possible.Submit a request