Getting and Using an Access Token

Oauth2

API access is controlled with bearer tokens obtained from the OAuth2 provider on behalf of a registered UCF user. Refresh tokens can be used to obtain access tokens when the originals expire.

For general background on the OAuth2 process, check out our article in Authentication.

API Key Alternative

As an alternative to OAuth, you may ask your users to generate a token via the CCH and provide it to your application via a form field or similar mechanism. These tokens are used identically to those obtained via OAuth, and included in the Authorization header of each API request. They only grant access to data from the account that generated them. This type of token does not expire after a set amount of time, but can be manually revoked by the user who generated it.

Obtaining a Token

1. The client (your application) redirects the user our OAuth2 provider
   The user must be redirected to:
   

   https://auth.unifiedcompliance.com/authorize

   Example:

   https://auth.unifiedcompliance.com/authorize?client_id=YOUR_CLIENT_ID&response_type=code&state=SOME_RANDOM_STRING_YOU_GENERATE&scope=read&redirect_uri=https%3A%2F%your-application.com%2Fauthorize

   Required parameters:
   Parameter	Value
   client_id	The client ID of your registered application (specified in the CCH)
   redirect_url	The URL under your control where users are redirected after authorization - note that this must match the redirect_uri associated with your client ID, changing it to something else won't redirect the user elsewhere but will cause an error instead (specified in the CCH)
   response_type	The OAuth2 flow to use - currently only "code" (3-legged authorization code flow) is supported
   scope	The scope(s) that the resulting token will have access to.
   state	A secure, random string to protect against attacks like CSRF

2. The user logs into our authentication server with their CCH credentials
3. The OAuth2 provider redirects the user to the client's (your application's) redirect URI (specified in the CCH)
   The following parameters are included in the query string:
   

   Parameter	Value
   code	The authorization code which entitles your application to obtain a token on the user's behalf using its client credentials
   state	This must be identical to the original state string to ensure the request is genuine

   Example:

   https://your-application.com/authorize?code=xyz123&state=SOME_RANDOM_STRING_YOU_GENERATE

4. The client (your application) obtains a bearer token and refresh token.
   
   Make a POST request with a Content-Type of application/x-www-form-urlencoded header and URL encoded parameters to:
   

   https://auth.unifiedcompliance.com/token

   Include the following fields:
   

   Parameter	Value
   client_id	The client ID of your registered application
   client_secret	The client secret of your registered application - treat this as a password and never expose it
   code (for "authorization_code" grants only)	The authorization code obtained by the client in step 2
   grant_type	Currently "authorization_code" (use authorization code to obtain bearer and refresh tokens) and "refresh token" (use refresh token to obtain new bearer token) are supported
   redirect_url	The URL under your control where users are redirected after authorization - note that this must match the redirect_uri associated with your client ID, changing it to something else won't redirect the user elsewhere but will cause an error instead
   refresh_token (for "refresh_token" grants only)	The refresh token obtained using the "authorization_code" grant

Example: Obtain bearer token and refresh token

Request

POST /token HTTP/1.1
Host: auth.unifiedcompliance.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=f140088c4155ac86d9d57aa324a30607e0cfc023&client_id=someclient&client_secret=abcd1234&redirect_uri=http://clientdomain.com/authorize

Response

200 OK

{

"access_token": "a0e9ae4d67c6f6c49c5163796cc233512360fd2b",

"expires_in": 3600,

"token_type": "bearer",

"scope": "read",

"refresh_token": "d60dffd6de7356c49b9ccdb92fb3f8a294981ca9"

}

Authenticating With Token

Once you have obtained a valid bearer token, include it in the Authorization header with each request to the API:

Authorization: Bearer BEARER_TOKEN

GET / HTTP/1.1

Host: [api hostname]

Authorization: Bearer [token]

If no token is provided, the request will be refused: 

If you receive this error and have provided an Access Token, other common causes include an invalid or expired token or malformed Authorization header (e.g. "Bearer" misspelled).