Setup on the CCH
Before you can use the Common Controls Hub API, you first need to create an application which will give you a client_id and a client_secret.This information is used to negotiate with our API using OAuth2 to obtain an Access Token which is used to get data on the behalf of your end user.
Getting an Access Token
The CCH API uses the standard OAUTH2 Web Application flow to distribute Access Tokens.
We're going to dive into the basics of this process here. If you want to dive in a little deeper we have a step by step example (with code samples) on how to navigate this process and here is a great article that will give you a little more information.
Basically, the way the OAuth web application flow works is:
- Your application sends the end user to our website with your client_id, scope and Redirect URL
- The end user is presented with a prompt to authorize access to their account
- If the end user allows access, our website redirects them to the Redirect URL with an Authorization Code
- Your application queries our API with the Authorization Code, client_id, client_secret, and Redirect URL
- Our API validates the Authorization Code and issues Access Token and Refresh Tokens which your application uses to access the API
An outline of this flow is below:
Querying the CCH API
Once you have a end user's Access Token, you can access any of the public API endpoints and data accessible to that end user.
You must include the Access Token in the header of all of your requests to the CCH API.
Expand Example: Headers
GET / HTTP/1.1Host: api.unifiedcompliance.comAuthorization: Bearer [Your Token Here]
Refresh Tokens
When an Access Token is issued it also comes with a Refresh Token.
Access Tokens expire after an hour. After an hour has passed the token must be refreshed by querying the CCH API using the Refresh Token. If the Refresh Token is valid, and the user has not revoked access to your application a new Access Token is issued.
Refresh Tokens expire after 2 weeks. Once a Refresh Token has expired the user must be reauthenticated.
If you attempt to query the CCH API with an expired Access Token you will receive error 401.
Expand Example: Expired Token Response
401 Unauthorized{"message":"The access token provided has expired"}
There are two methods for handling Access Token expiration. Each one has it's upsides and downsides depending on your application.
Method 1: Check to see if a user's Access Token has expired when they attempt to perform an action using the CCH API
Method 2: Continually check the expiration time of every access token in your system and automatically refresh when a token expires
