This article explains how to generate and manage credentials for Personio public APIs. APIs allow Personio to share data with other services or tools. API credentials act like a key that controls the flow of information and decides what gets shared.

Before you start

• To use the Marketplace and set up integrations, you need to have edit rights for Marketplace Integration and API.
• To create your own custom integration using our public API, you need the Core Pro Personio plan.
• Personio automatically creates API credentials for all integrations except custom ones.

Learn about API credentials

API credentials build connections and protect communication between applications. In Personio, the system creates API credentials for the following:

• Recruiting API
• Integrations from Personio
• Integrations from Personio partners

You cannot manage these credentials yourself. You can update these integrations through the Personio Marketplace. The system sets most API permissions to the level needed for the integration to work. You usually generate and manage API credentials manually for custom integrations.

How API access works for custom integrations

When you set up a custom integration, you define its Access rights (for example, whether it can read or write data in areas like Employees, Attendances, Time off, and Documents). The integration then uses its API credentials (Client ID and API secret) to authenticate API requests.

API access works differently from employee role-based access in Personio. Employee role permissions control what users can see and do in the Personio interface, but they don't control what custom integrations can retrieve via the API. This means you cannot limit API access to only the employees in a specific role using employee role permissions.

Note:
Anyone with access to API credentials can retrieve almost all data from the Personio account through the API, regardless of their permissions in Personio. Employee role permissions apply to the interface only — they don't restrict what can be retrieved through the API. Only grant API credential access to trusted users.

Generate API credentials for custom integrations

To generate credentials for custom integrations:

1. Go to Marketplace > Connected Integrations.
2. Click Create custom integration at the top right of the screen. This button is only available if you have the Core Pro Personio plan. If you cannot see it, check your current plan in Settings > Account & support > Subscription & billing to confirm you're on Core Pro.
3. Configure the setup.

Note:
Write permissions do not include read access. If you want to retrieve data via our APIs, you also need to grant Read permissions.

The following table shows what each permission allows a third-party system to do. Some permissions are available for read access only. For endpoint details, visit the Developer Hub. 

Note:
Enabling Attendances access also allows your integration to use the Projects API endpoint (/v2/projects) for custom integrations. There is no separate Projects permission in the credential settings.

Attribute names in the Readable employee attributes and Readable legal entities selectors appear in English, regardless of your Personio account language. If you cannot find an attribute, search for its English equivalent.

Authenticate your API requests

After generating API credentials, you need to exchange them for a Bearer token before making any API call. You cannot use your Client Secret directly as a Bearer token.

To get a Bearer token:

1. Send a POST request to the auth endpoint: POST https://api.personio.de/v2/auth/token with Content-Type: application/x-www-form-urlencoded and the following parameters: grant_type=client_credentials, client_id={your_client_id}, client_secret={your_client_secret}
2. The response returns a Bearer token. Include it in the Authorization header of every subsequent API request: Authorization: Bearer {token}

Bearer tokens are valid for 24 hours. Generate a new token after they expire. You can find your Client ID and Client Secret in Settings > Security & integrations > API credentials.

Update API credentials for custom integrations

To update the permissions for custom integrations:

1. Go to Marketplace > Connected integrations.
2. Click the integration to update.
3. In the window that appears, make your changes.
4. Save your settings.

You can also reset the API credentials from here by following the instructions.

Disconnect or disable API credentials for custom integrations

To disconnect or disable API credentials for custom integrations:

1. Go to Marketplace > Connected integrations.
2. In the Action column, click the three dots.
3. Click Disable to temporarily disable credentials.
4. Click Disconnect to permanently delete credentials.

If you're unsure if an integration is still in use, choose Disable rather than Disconnect. Disabling makes the integration inactive but keeps it visible in Marketplace > Connected integrations. If the integration turns out to be active, you can re-enable it. Disconnecting permanently removes the credentials and cannot be undone.

Access technical documentation

Find all API documentation in our Developer Hub. This includes endpoints, webhooks, data details, and tutorials. The Developer Hub has two versions with different content. Webhook information is in version 2.0. To switch versions, click the version number at the top of the home page.