Skip to main content

Create and configure a Service account API key

Create a Service account API key for API v4 and control what data it can access through roles and permissions

A Service account API key lets you connect external services to PeopleForce while controlling which employee data and company-level actions are available through the API. Unlike a Company API key, access for a Service account is managed through a dedicated role in Roles & permissions.

🔑 Generate a Service account API key

  1. Go to Settings → API keys.

  2. Click + New.
    ​

  3. Enter a name for the key.

  4. In the Type field, select Service account.
    ​

  5. If required, specify the IP addresses that are allowed to use the key.

  6. Click Generate. Copy the generated API key and save it in a secure location. For security reasons, PeopleForce will not display the full key again after it has been generated.

💡 If Service account is not available as an API key type, contact support@peopleforce.io to enable it.

👤 Create a Service account role

After generating the key, create a role that defines its access.

  1. Go to Settings → Roles & permissions.

  2. Click New role and select Service account.
    ​

  3. Enter the role name and, optionally, a description.

  4. Under Who is assigned this role?, select the Service account API key you created.
    ​

  5. Then configure permissions for this role to determine what the Service account can access through the API.

🔐 Configure access to employee data

  1. Open the People tab to define which employees and information the Service account can access.

  2. Under Whose data can members access?, choose the employees whose data should be available:

    1. Specific people – use conditions to define which employees the Service account can access.

    2. Everyone – allow access to all employees.

    You can also choose whether terminated employees should be included.

  3. Then configure What can this role see? for the required employee data. Depending on the permission, you can provide:

    1. None – no access;

    2. View – read access;

    3. Edit – permission to make changes.

If the role does not include a particular employee, that employee will not be returned through the API. If the role does not have access to a specific field, that field will be omitted from the API response.

🏢 Configure company permissions

  1. Use the Company tab to grant access to company-level functionality.

  2. Enable the required Manage … permissions depending on what the integration needs to do, for example, when working with company-wide data such as departments or locations.

  3. Grant only the permissions required for your integration.

🔌 Use the key with API v4

Service account keys are used with PeopleForce API v4.

Pass the generated key in the request header: X-API-KEY

API v4 currently does not include all endpoints available in API v3. Before setting up an integration, check whether the required endpoints are available in the API v4 reference.

📚 For more information about authentication, see API v4 authentication.

Related Articles
Did this answer your question?