This guide details how developers at Check Integration Partners can securely access customer data that lives in Check to power a product experience through one of Check's existing Partners.

There are four important entities that will be referred to throughout this document:

• Check — this is us! 👋
• Integration Partner — this is you! You would like to access customer payroll data that lives within Check on behalf of a Check Partner.
• Partner — this is a customer of Check, and is likely also a customer (or future customer) of the Integration Partner. The Partner is the entity who ultimately owns the payroll customer relationship with the employer, and is aiming to deliver an integrated experience to that customer through a software platform built on top of Check and enhanced by the Integration Partner.
• Employer — this is the end employer running payroll on the Partner’s software. They grant access to their data to the Integration Partner to power an additional experience within the Partner’s software.

Process Overview

1. Check’s Integrations are ultimately in service of our Partners, who are software platforms that have built payroll businesses on top of Check’s infrastructure. This is the first step.
2. The second step is an Employer signs up to run payroll on the product of one of Check’s partners. In the course of this customer relationship they may sign up for additional services, some of which may be offered by an Integration Partner.
3. If and when an Employer grants consent for an Integration Partner to access their data to unlock an additional service, the Partner makes an API call to Check to authorize the Integration Partner to access that Employer’s data.
4. At this point, Check sends an authorization code to the Integration Partner, which can then be exchanged for an access token. That token is effectively equivalent to an API key, but has scoped access pursuant to the Integration Partner and permission level, and the specific employer in question.
5. Finally, an employer may or may not have a direct relationship and/or login to the Integration Partner’s product or website.

Technical Details

Creating an OAuth Access Token

All requests made by an Integration Partner to retrieve payroll data, and create, update, or delete API objects should use an OAuth Access Token.

In order to receive an OAuth Access Token, a Check Partner must first make a request to grant the Integration Partner access to a specific company’s data.

This request will look like the below. You can find more information on this API request here.

curl \
  -H "Authorization: Bearer <Partner API Key>" \
  "https://sandbox.checkhq.com/integrations/partners/{integration_id}/authorize"
  -d '{
    "integration_permission": "{integration_permission_id}",
    "company": "{company_id}",
    "tos_timestamp": "{timestamp_of_tos_signature}",
    "product_purchase_timestamp": "{timestamp_of_product_purchase}"
  }'

When this request is made, Check will send a callback request to a redirect URI specified by the Integration Partner. The request that Check makes will contain an authorization code, which can be exchanged for an access token.

Expectations for your Redirect URI

Your redirect URI should expect a receive request with a code as a query parameter (as in a standard OAuth implementation).

GET "https://integration.partner.com/auth/check/callback?code={code}"

Query Parameters:
  code={code}

Expected Response: None

Status: 200

How to Exchange the Code for a Token

Once you receive the code from the call above, you should make a POST request with the code included in the form data to retrieve a set of access and refresh tokens.

POST "https://sandbox.checkhq.com/oauth/token/"

Headers:
 "Content-Type: application/x-www-form-urlencoded"

Request (form data):
  "client_id={client_id}"
  "client_secret={client_secret}"
  "code={authorization_code}"
  "redirect_uri=https://integration.partner.com/auth/check/callback"
  "grant_type=authorization_code"

Response:
{
  "access_token": "{access_token}",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "...",
  "refresh_token": "{refresh_token}"
}

How to Refresh an Access Token Using a Refresh Token

POST "https://sandbox.checkhq.com/oauth/token/"

Headers:
 "Content-Type: application/x-www-form-urlencoded"

Request (form data):
  "client_id={client_id}"
  "client_secret={client_secret}"
  "refresh_token={refresh_token}"
  "grant_type=refresh_token"

Response:
{
  "access_token": "{new_access_token}",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "...",
  "refresh_token": "{new_refresh_token}"
}