This article provides a short guide for integrating an existing identity management system or Identity Provider (IdP), with Peakon’s SCIM 2.0 API for the purpose of automatic provisioning and updating of employee records. It does not intend to duplicate the information available in the SCIM 2.0 specification, but rather outline specific characteristics of Peakon’s SCIM 2.0 implementation. In this guide, Peakon will be referred to as the Service Provider (SP).

Enabling the Employee Provisioning integration

IT administrators can configure this by first clicking the settings icon in the bottom left corner of the Peakon dashboard, choosing Integrations, and then selecting Employee Provisioning from the list of integrations. Click the yellow Enable button and you’ll be taken to the page you see in the screenshot below.

If you use an existing IdP that supports the SCIM 2.0 protocol, such as Microsoft Azure Active Directory or Okta, no custom integration is needed and you can go ahead and simply configure the IdP for automatic provisioning to Peakon as a standard SCIM 2.0 Service Provider.

If your existing systems require a custom integration, use the SCIM URL and OAuth Bearer Token in the following sections.

The basics

The base URL for all SCIM operations is https://api.peakon/scim/v2. The API relies on Bearer Token authentication, and as such the authentication token from above should be provided in the Authorization header in the  of any request to the API that requires authentication, with the value "Bearer {token}".

Supported operations

Get all users

Method: GET /Users
Requires authentication: Yes

Returns all already provisioned users in the system. This operation supports pagination as described in the SCIM specification. It also supports filtering by:

  • userName
  • emails
  • externalID
  • id (internal Peakon ID)

For additional fields, see the Peakon schema extension section below.

Get user

Method: GET /Users/{id}
Requires authentication: Yes

Returns a provisioned user by their unique identifier. The identifier in this case is the internal Peakon ID of the user returned in the response of the Create user operation.

If you wish to retrieve the user by externalId instead, consider using the Get all users operation and filter by externalId, which would have been provided when the user was first created/provisioned.

Create user

Method: POST /Users
Requires authentication: Yes

Provision a new user. Peakon requires the following fields to be provided for each new user:

  • externalId: String ID used in the external system (max 128 characters)
  • userName: The primary email of the user (max 256 characters)
  • name.givenName: The first name of the user (max 128 characters)
  • name.familyName: The last name of the user (max 128 characters)

The following fields are optional:

  • active: A boolean indicating whether the user is active or disabled. Can be used for de-provisioning if a full deletion is not desired.

For additional fields, see the Peakon schema extension section below.

Update user

Method: PUT /Users/{id}
Requires authentication: Yes

Updates an existing user. Supports the same fields as the Create user operation.

Patch user

Method: PATCH /Users/{id}
Requires authentication: Yes

Makes partial updates to a user. As defined by the the SCIM 2.0 specification, the patch operation supports updating one or more specific fields of a user, through a set of of "add", "remove" or "replace" operations.

Delete user

Method: DELETE /Users/{id}
Requires authentication: Yes

Deletes the user.

Get schemas

Method: GET /Schemas
Requires authentication: Yes

Returns all schemas and fields available for a given company, including custom attributes (e.g. Manager, Date of Birth, Department etc.) set up by the company’s Peakon administrator.

Get Service Provider config

Method: GET /ServiceProviderConfig
Requires authentication: No

Returns the Service Provider configuration of the SCIM API including it's capabilities and supported features.

Peakon schema extension

In addition to the basic fields covered under “Operations” section, Peakon provides a custom schema extension to allow field data for custom attributes (e.g. Manager, Date of Birth, Department etc.). The format of this extension follows the format specified in the SCIM 2.0 specification

The value type of the custom attributes depend of the type of attribute:

  • Option type attributes (e.g. Department): A string value (max 256 characters)
  • Date type attribute (e.g. Date of birth): A DateTime string (ISO 8601 format)
  • Number type attribute (e.g. Salary): An Integer value
  • Employee type attribute (e.g. Manager): A string value containing the email of the referenced employee. Since employee type attributes reference other employees in the system, the referenced employee needs to exist in the system beforehand. This could be achieved by a two-step provisioning, including only basic fields in the first step and extended fields in the second.

Custom attributes are provided as a sub-object of the main resource fields, e.g.

{
   "name" : {
      "firstName": "Jane",
      "lastName": "Smith"
   },
   “urn:ietf:params:scim:schemas:extension:peakon:2.0:User”: {
      “Business Unit”: “Engineering",
      “Department”: “IT"
   }
}

To retrieve the schemas that are supported for your company, including available fields, call the Get schemas endpoint described above.

Rate limiting

The Peakon SCIM API is rate limited at 25000 requests/hour. Any integration should throttle its API calls to make sure this limit is not exceeded.

External documentation

The following sections of the SCIM 2.0 specification are relevant to the above operations for anyone looking to create a custom integration with the Peakon SCIM API.

Did this answer your question?