Authentication

Customer Consent and Verification

Overview

Partner authentication works similarly to client credentials, but with an additional one-time consent and verification step.

HCSS CustomerHCSS MarketplaceYour ApplicationHCSS IdentityBrowse to ApplicationAdd ApplicationRedirectEnsure user is authenticated in your app before continuingAuthorization Code FlowLookup HCSS Company Id from tokenPersist association between your app's user and their HCSS Company IdHCSS CustomerHCSS MarketplaceYour ApplicationHCSS Identity

This only needs to be performed once, unless the customer removes your application or the scopes you have configured change.

Details

Step 1: Customer Consent

Before you can request data on behalf of HCSS customers, an admin from their company must connect to your application in the HCSS Marketplace.

Connecting Apps

Upon clicking connect they will be presented with a consent screen

Connecting Apps

If they confirm the connection, they will be redirected to the redirect url configured in your app's settings.

Step 2: Verification and Association

After the customer is redirected to your app, ensure that they are signed in, and then perform an authcode pkce flow using the code grant type. This step involves calling the authorize endpoint. The customer will be redirected back to your site with the authorization code.

The next step will be to redeem the authorization code for an HCSS token. This step involves calling the token endpoint. This token will contain a CompanyId claim which contains the HCSS company id you will need in the next step. You will need to store the HCSS Company Id in your app and associate it with your app's user.

Step 3: Requesting Tokens and Making API calls

Overview

Once the consent and verification has been performed, your application can start getting data on behalf of any company that has consented.

This flow takes advantage of the company grant type.The company flow is similar to client_credentials, but includes a required CompanyId parameter.

Your ApplicationHCSS IdentityHCSS Product APIsLookup HCSS Company Id from previous stepsRequest token using company flowInclude token in the Authorization header and make API callsYour ApplicationHCSS IdentityHCSS Product APIs

Details

Request a token using the company grant type

Once the customer has consented, and you have the HCSS Company Id, you can then begin making requests on behalf of that user's company by using the company grant type. This flow is similar to client credentials, but includes an additional CompanyId parameter.

This flow will only work if a customer has added your application in the marketplace.

Once you have the token, you can then make API calls to any HCSS API that you have configured and requested scopes for.