Authorization Code Flow

Authorization Code Flow is used to request OAuth tokens when your application wants to interact with data on behalf of a user.  This flow is required if you are interacting with other companies' data.  We recommend using an SDK, such as the oidc library when implementing this flow.

For this flow, HCSS will provide 2 pieces of information:client_id, and one or more scopes.  In addition, you will need to provide HCSS with aredirect_uri, which is the URI where our servers will redirect the user if they consent to sharing their data with your application.

First, direct the user to the authorize endpoint of our Identity API.  For example,

 https://api.hcssapps.com/identity/connect/authorize
     ?client_id=YOUR_CLIENT_ID
     &scope=YOUR_SCOPE
     &response_type=code
     &redirect_uri=YOUR_REDIRECT_URI
     &state=YOUR_OPAQUE_VALUE

Theclient_id is provided by HCSS.  Thescope parameter is a space-separated string of scopes that HCSS provides as well.  The user will be presented with a consent page, informing them of the scopes that your application is requesting.  If the user consents, your application will get a callback at theredirect_uri that you specified.  For example, if your redirect_uri is https://hcss.com/redirect, the callback will look like:

https://hcss.com/redirect
     ?code=g0ZGZmN
     &state=YOUR_OPAQUE_VALUE

Thecode is an authorization code that you will exchange for anaccess_token.  You should verify that the state parameter is the same value that you sent to the/authorize endpoint.  This protects against CSRF attacks.

Here is an example request that exchanges the code for an access_token, using cURL:

curl --request POST
    --url 'https://api.hcssapps.com/identity/connect/token'
    --header 'Content-Type: application/x-www-form-urlencoded'
    --data-urlencode 'grant_type=authorization_code'   
    --data-urlencode 'client_id=YOUR_CLIENT_ID'
    --data-urlencode 'code=g0ZGZmN'
    --data-urlencode 'redirect_uri=YOUR_REDIRECT_URI

If the request was successful, you will receive an access_token and can now make an API call on behalf of the user!

For a more detailed overview of authorization code flow, check out the docs on auth0.