solon-aguiar/oauth-reference-integration

Open source Checkr integration

Reference Integration

This is a sample application demonstrating an end to end Checkr integration. It outlines best practices and patterns we see Checkr integrations adopt, and will help you develop a Checkr certified integration. It focuses on two use-cases:

• How to use the Checkr-Hosted Signup flow to connect your customers to Checkr.
• How to order background checks and report results using Checkr Embeds.

You can refer to this application if you are building either one or both use-cases.

Contents

• Use case: Connecting customers
• Use case: Using Embeds to order background checks
• Live Sandbox
• Technical Documentation
• Running it locally
• Got feedback?

Use case: Connecting customers

With Checkr OAuth, your customers can easily connect their Checkr account with your product. It gives your product the ability to make API calls on behalf of your customers. This described in more detail in our partner guide.

Checklist

• Signing up for a new Checkr account, or connecting an existing account.
• Waiting for account credentialing.
• Disconnecting a customer account from a partner.

Application components

Component	Responsibility	Code walkthrough
oauth.js	Handles OAuth and Webhooks	walkthrough
CheckrConnectLink.js	Link to connect account with Checkr	walkthrough

sequenceDiagram
  autonumber

    Note right of App Frontend: CheckrConnectLink pressed
    Note right of Partner customer signup flow: Checkr Account created

    App Frontend->>+Partner customer signup flow: Navigate to Checkr Sign-Up Flow URL
    Partner customer signup flow->>+oauth.js: Navigate to redirect URL
    oauth.js->>+Checkr: Request OAuth Access token
    Checkr->>+oauth.js: Respond with OAuth Access token
    oauth.js->>+App Database: Persist and encrypt OAuth Access token in App Database
    oauth.js->>+App Frontend: Redirect to App Frontend

    Note right of App Frontend: Account is waiting credentialing
    Checkr->>+oauth.js: Send account.credentialed webhook
    oauth.js->>+App Database: Update Checkr account state
    Note right of App Frontend: Account is credentialed

    App Frontend->>+Checkr: POST /oauth/deauthorize
    Checkr->>+oauth.js: HTTP 200
    Note right of Checkr: Token has been deauthorized
    oauth.js->>+App Frontend: HTTP 204
    Checkr->>+oauth.js: Send token.deauthorized webhook
    oauth.js->>+App Database: Delete access token from database
    Note right of App Frontend: Account is disconnected

Loading

Use case: Using Embeds to order background checks

Embeds provide Javascript and React components to quickly build an experience to order background checks and view results. Read more about it here.

Checklist

• Acquiring session tokens from Checkr to authenticate embeds.

Application components

Component	Responsibility	Code walkthrough	Diagram
embeds-session-tokens.js	Handles requesting a Session token from Checkr	walkthrough	diagram

Live sandbox

An instance of this application is hosted at checkr-oauth-integration.herokuapp.com. It is connected to a demo staging Checkr account which does not run real background checks.

You can also deploy this using your own Heroku account, and connect it to your Checkr account.

Technical Documentation

• API docs
• Partner Guide
• Embeds docs

Running it locally

View the development page to run this project locally.

Got feedback?

Open an issue in this repository to ask a question or give us feedback.