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).

IT administrators can configure this by going into Administration > Integrations > Employee provisioning. Click the Connect button and you will see the options 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 base URL for all SCIM operations is https://api.peakon.com. 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}".

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:

For additional fields, see the schema extension section below.

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.

Method: POST /Users
Requires authentication: Yes

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

The following fields are optional:

For additional fields, see the schema extension section below.

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

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

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.

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

Deletes the user.

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.

Method: GET /ServiceProviderConfig
Requires authentication: No

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

Peakon supports the enterprise user schema extension as defined in the SCIM 2.0 specification.

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:

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.

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.

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.