{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-embeds/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","admonition"]},"type":"markdown"},"seo":{"title":"Getting Started","description":"Checkr developer documentation for background check APIs, embeds, and partner integrations."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pre-requisites","__idx":1},"children":["Pre-requisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have signed up for a Checkr account either directly with Checkr or through a partner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Except for Sign-up & Connect embed"]},": You have implemented ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/partners/getting-started#retrieve-an-access-token"},"children":["Checkr OAuth"]}," if you are a partner."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"to-use-a-checkr-embed-within-your-application","__idx":2},"children":["To use a Checkr embed within your application"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Load ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/embeds/getting-started#load-checkrs-web-sdk"},"children":["Checkr's Web SDK"]}," directly through CDN. This ensures you always have the latest version."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the embed to your frontend code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Except for Sign-up & Connect embed"]},": Implement ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/embeds/getting-started#add-authentication"},"children":["authentication"]}," for the embed using a SessionToken."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally, customize the embed based on your application's needs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"load-checkrs-web-sdk","__idx":3},"children":["Load Checkr's Web SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["First, Load Checkr's Web SDK using CDN"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script src=\"https://cdn.jsdelivr.net/npm/@checkr/web-sdk/dist/web-sdk.umd.js\"></script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/embeds/examples"},"children":["Examples"]}," section below showcases some examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-authentication","__idx":4},"children":["Add authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Sign-up & Connect embed no previous authentication is required. In fact, Sign-up & Connect embed will implement most of the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/partners/getting-started#connect-your-customers-to-checkr"},"children":["Checkr OAuth"]}," flow for you. It provides your application with an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow"},"children":["Oauth Authorization Code"]}," to exchange for an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/partners/getting-started#connect-your-customers-to-checkr"},"children":["OAuth access token"]},", which can be used by your application to make API calls to Checkr on behalf of your customers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This Access Token must be used to request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionToken"]},"s for authentication using other embeds."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-on-keeping-your-access-token-secure","__idx":5},"children":["Notes on keeping your Access Token secure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Be aware that the following token exchanges ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must take place within your own backend application"]}," to avoid exposing Access Tokens in your frontend application, which are considered ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sensitive secrets"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exchange of the Oauth Authorization Code for an Access Token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exchange of the Access Token for a Session Token (specific to use with embeds.)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-authentication-for-other-embeds","__idx":6},"children":["Add authentication for other embeds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/authentication-v3.3ee93cbf5e9e1b2fcfb580f97e591c01406e49f7112fad4aaa26fc671595e0a7.9c1bb791.png","alt":"Session Token Authentication"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["First, the embed authenticates with Checkr."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The embed sends a request from your application's frontend to your application's backend for a Checkr SessionToken."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your application's backend must first authenticate the logged in user using its own mechanisms, and then pass the request to Checkr."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checkr sends a SessionToken to your backend in response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your application's backend then passes the SessionToken to the embed running on your application's frontend."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While authentication is processing, the embed displays a loading state in your app. Then, the embed fetches and renders the returned data."]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":5},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The embed uses Checkr APIs to request data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checkr APIs return the requested data directly to the embed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the requested data is returned, the embed renders within your application."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"embed-authentication-flow","__idx":7},"children":["Embed authentication flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an Embed loads for the first time, it sends an HTTP POST request to your backend, requesting a SessionToken. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTokenPath"]}," property to set your application's backend endpoint to use."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, your application's cookies are sent to your backend to help you authenticate the user. To enable authentication via headers (such as bearer tokens), use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTokenRequestHeaders"]}," property as shown below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTokenPath"]}," is a path to request the token, not the token itself. You should not be passing the token as a prop directly to the embed."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const embed = new Checkr.Embeds.NewInvitation({ sessionTokenPath: '/your-backend/session-tokens', sessionTokenRequestHeaders: () => ({ Authorization : `Bearer ${token}` })})\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"React","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"<NewInvitation sessionTokenPath='/your-backend/checkr-session-tokens' sessionTokenRequestHeaders={() => ({ Authorization : `Bearer ${token}` })}/>\n","lang":"jsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Do not use a public endpoint for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTokenPath"]}," property. Be certain to complete your application's user authentication and authorization before responding to the request."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run your application's user authentication and authorization rules before requesting Checkr to acquire a SessionToken."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-1-the-embed-requests-a-sessiontoken-from-your-backend","__idx":8},"children":["Step 1: The embed requests a SessionToken from your backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The embed will use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTokenPath"]}," property to request a SessionToken from your backend."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const embed = new Checkr.Embeds.NewInvitation({ sessionTokenPath: '/your-backend/session-tokens' })\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"React","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"<NewInvitation sessionTokenPath='/your-backend/checkr-session-tokens' />\n","lang":"jsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-2-send-a-request-for-a-sessiontoken-from-your-backend-to-checkr","__idx":9},"children":["Step 2: Send a request for a SessionToken from your backend to Checkr"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr provides two means to acquire this SessionToken: one for our direct customers, and one for our partner developers."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customers building directly to the Checkr APIs:"]}," Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.checkr.com/account/developer_settings"},"children":["API Keys"]}," found in the Checkr Dashboard to request SessionTokens."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partner developers, building partner applications:"]}," Use the OAuth Access Token acquired through ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/partners/getting-started#connect-your-customers-to-checkr"},"children":["Checkr OAuth"]}," to request SessionTokens. This is a pre-requisite for using Embeds. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/partners/introduction"},"children":["Checkr Partner Guides"]}," for more information."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your application's backend receives the HTTP Post request from the embed, run authentication and authorization rules based on your application logic (for the current user), and then make the following call to Checkr."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scopes are used to determine what access you are requesting for."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use case"},"children":["Use case"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["order"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NewInvitation Embed, ReportsOverview Embed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["disclosure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disclosure & Consent Embed"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{checkr-api-host}/web_sdk/session_tokens"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr API host:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Staging: https://api.checkr-staging.com/v1"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Production: https://api.checkr.com/v1"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following as the request JSON payload:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Partner Request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n  --url {checkr-api-host}/web_sdk/session_tokens \\\n  --user your-checkr-oauth-access-token: \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n\t\"scopes\": [\"order\"]\n}'\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Direct Customer Request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n  --url {checkr-api-host}/web_sdk/session_tokens \\\n  --user your-checkr-api-key: \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n\t\"scopes\": [\"order\"],\n\t\"direct\": true\n}'\n","lang":"shell"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-3-checkr-responds-to-your-backend-with-a-sessiontoken","__idx":10},"children":["Step 3: Checkr responds to your backend with a SessionToken"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkr will respond with a SessionToken."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"token\": \"example-session-token\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"step-4-return-the-acquired-sessiontoken-from-your-backend-to-your-frontend","__idx":11},"children":["Step 4: Return the acquired SessionToken from your backend to your frontend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return the JSON response (from above) from the Checkr API back to your frontend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SessionTokens are short-lived. If they expire, the embed will automatically attempt to renew them by re-executing Steps 2 to 4."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-fakemode-to-preview-embeds","__idx":12},"children":["Use fakeMode to preview Embeds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fake mode lets you play with the Embed without it making any API calls. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fakeMode"]}," is enabled in an embed (all embeds support it), the embed would work using canned data."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const embed = new Checkr.Embeds.NewInvitation({ fakeMode: true })\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"React","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"<NewInvitation fakeMode={true} />\n","lang":"jsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-a-staging-account-to-test-embeds","__idx":13},"children":["Use a Staging account to test Embeds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you want to test with a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/getting-started#request-a-staging-account"},"children":["Checkr Staging account"]},", you can pass an additional param to any embed, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["env: \"staging\""]}," to run the embeds against Staging. You can omit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["env"]}," param entirely, or specify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["env: \"production\""]},", to use a production account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Embeds do not support mixed Staging and Production usage on the same page - ensure all concurrently rendered embeds are using the same environment."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const embed = new Checkr.Embeds.SignUpFlow({\n  env: 'staging'\n  oauthTokenPath: '/your-backend/checkr-staging-oauth-token',\n  partner: { id: 'abcdef1', name: 'Enterprise Partner Staging' },\n});\n","lang":"js"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"React","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"<SignUpFlow\n  env='staging'\n  oauthTokenPath='/your-backend/checkr-staging-oauth-token'\n  partner={{ id: 'abcdef1', name: 'Enterprise Partner Staging' }}\n/>\n","lang":"jsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":14},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While Embeds do not rely on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/webhooks"},"children":["Webhooks"]},", you can definitely use it in combination with Embeds to build more advanced features such as workflow automation in your product."]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Pre-requisites","id":"pre-requisites","depth":3},{"value":"To use a Checkr embed within your application","id":"to-use-a-checkr-embed-within-your-application","depth":3},{"value":"Load Checkr's Web SDK","id":"load-checkrs-web-sdk","depth":2},{"value":"Add authentication","id":"add-authentication","depth":2},{"value":"Notes on keeping your Access Token secure","id":"notes-on-keeping-your-access-token-secure","depth":3},{"value":"Add authentication for other embeds","id":"add-authentication-for-other-embeds","depth":2},{"value":"Embed authentication flow","id":"embed-authentication-flow","depth":3},{"value":"Step 1: The embed requests a SessionToken from your backend","id":"step-1-the-embed-requests-a-sessiontoken-from-your-backend","depth":4},{"value":"Step 2: Send a request for a SessionToken from your backend to Checkr","id":"step-2-send-a-request-for-a-sessiontoken-from-your-backend-to-checkr","depth":4},{"value":"Step 3: Checkr responds to your backend with a SessionToken","id":"step-3-checkr-responds-to-your-backend-with-a-sessiontoken","depth":4},{"value":"Step 4: Return the acquired SessionToken from your backend to your frontend","id":"step-4-return-the-acquired-sessiontoken-from-your-backend-to-your-frontend","depth":4},{"value":"Use fakeMode to preview Embeds","id":"use-fakemode-to-preview-embeds","depth":2},{"value":"Use a Staging account to test Embeds","id":"use-a-staging-account-to-test-embeds","depth":2},{"value":"Webhooks","id":"webhooks","depth":2}],"frontmatter":{"title":"Getting Started","description":"Learn how to load the Checkr Web SDK, add authentication, and start using Checkr Embeds in your application.","seo":{"title":"Getting Started"}},"lastModified":"2026-11-05T02:20:48.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/embeds/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}