This feature is currently undergoing maintenance. The information in this article may not be fully up-to-date.

This article explains how to generate and manage (update, disable, re-enable, and remove) credentials for the Personio Personnel Data APIs and the Personio Custom Reports API.

The credentials for our Recruiting API and for integrations developed by Personio are system-generated and are not managed by Administrators.

What are API credentials in Personio?

API credentials allow data to be exchanged between Personio and another service or tool. This helps you to build connections between Personio and your own system, or set up integrations with third-party providers available in the Personio Marketplace.

• API credentials help to safeguard communication between applications and avoid unauthorized access that could lead to data breaches. For data security reasons, it's recommended that you generate new API credentials for each integration.
• You do not need to generate API credentials for integrations developed by Personio. They are system-generated and permissions are limited to the level necessary to run the integration.

Generate API credentials for Marketplace integrations

To generate API credentials for Integrations listed in the Personio Marketplace, follow these steps:

1. Go to Personio Marketplace to search for and select the integration you want to activate.
2. Click Connect to start the activation process. 
3. Continue the activation depending on the integration type. Some may require you to contact the integration partner directly. See our Activate Integrations from the Marketplace article for more info.

Generate API credentials for custom integrations

To generate credentials for custom integrations, follow these steps:

1. Go to Settings > Integrations > API credentials.
2. Click Generate new credential at the top right of the screen.
3. The Add new credential drawer appears.
4. In the Name field, enter a meaningful name (for example, 'Custom Reports') for the credentials.
5. Use the checkboxes to define the desired access levels.
   
   

   Employees	Select Read to allow third-party systems to pull employee data from Personio. Select Write to allow them to create and update data in Personio.
   Attendances	Select Read to allow third-party systems to pull attendance data from Personio. Select Write to allow them to create, update, and delete attendances in Personio.
   Absences	Select Read to allow third-party systems to pull absence data from Personio. Select Write to allow them to create and delete absences in Personio.
   Documents	Select Read to allow third-party systems to pull document category IDs from Personio.  Read access is necessary if you want to use the Write permission. Select Write to allow them to create
   Custom Reports	Select Read to allow third-party systems to retrieve all existing custom reports from Personio. Learn more about the Personio Custom Reports API. *When you select the Custom Reports checkbox, all attributes added to a custom report will be retrievable, no matter if the attribute has been listed under Readable employee attributes or not.

6. If you select Read next to Employees, the Readable employee attributes drop-down menu appears. Choose the employee attributes that should be transferred from Personio.
   
   
7. Click Generate new credential to generate the API credentials (client ID and secret). A message displays confirming that the credentials have been created.
   
   

   Note
   You will need the client ID and secret to activate the relevant integration. For more information, read our article Activate integrations from the Marketplace. Your 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.

For more info on assigning access levels for a specific integration, read the dedicated article in our Integrations section.

Manage API credentials

Update custom API credentials

Follow the steps below if you want to update the name of custom API credentials, the access levels, or the readable employee attributes. The client ID and secret cannot be updated.

• Go to Settings > Integrations > API credentials.
• Click the credentials you would like to update.
• In the drawer that appears, make the required updates.
• Click Save to implement the updates.

Note
For integrations developed by Personio, or Personio partners, it is not possible to update the API credentials via Settings. You can make updates to the integration via the Personio Marketplace; however, permissions are limited to the level necessary to run the integration.

Disable API credentials

If you want to temporarily disable API credentials, follow these steps:

1. Go to Settings > Integrations > API credentials.
2. In the list of all existing API credentials, toggle the switch beside the relevant credentials to Off.
3. The credentials will be disabled and the exchange of data will cease until the API credentials are re-enabled.

Re-enable API credentials

If you want to re-enable API credentials that have been temporarily disabled from working, follow these steps:

1. Go to Settings > Integrations > API credentials.
2. In the list of all existing API credentials, toggle the switch beside the relevant credentials to On.
3. The credentials will be re-enabled and the exchange of data will resume.

Remove API credentials

If you want to permanently delete and stop API credentials from working, follow these steps:

1. Go to Settings > Integrations > API credentials.
2. Click the relevant credentials.
3. In the sidebar that appears, click the bin icon and confirm that you want to remove the API credentials.
4. The credentials will be permanently removed.

Technical documentation

All the documentation for our APIs, including endpoints, information about the precise data transferred, and technical tutorials, is available in ourDeveloper Hub.