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

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

• Check — this is us! 👋
• Ecosystem 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. 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 Ecosystem Partner.
• Employer — this is the end employer running payroll on the Partner’s software. They grant access to the Ecosystem Partner to their payroll data in order to power an additional experience within the Partner’s software.

Process Overview

1. Check's Partners build payroll products on top of Check's infrastructure.
2. Employers sign 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 Ecosystem Partner.
3. If and when an Employer grants consent for an Ecosystem Partner to access their data to unlock an additional service, the Partner makes an API call to Check to authorize the Ecosystem Partner to access that Employer’s data.
4. At this point, Check sends an authorization code to the Ecosystem 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 Ecosystem 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 Ecosystem Partner’s product or website.

Technical Details

Creating an OAuth Access Token

All requests made by an Ecosystem 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 Ecosystem 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 Ecosystem 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 the following data as query parameters:

• code: The code will be exchanged for an access token in the next step, which will enable you to make authenticated calls against Check's API
• company: The company parameter contains the public ID of the Check company for which you are being granted an authorization code.
• partner: The partner parameter contains the public ID of the Check partner that owns the company in question.

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

Query Parameters:
	code={code}	
	company={company}
	partner={partner}

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}"
}