Getting 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.

OAuth 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"
}
Example: Obtain new bearer token using 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
Example: Successful request
 
Request
GET / HTTP/1.1
Host: [api hostname]
Authorization: Bearer [token]
Response 
200 OK
{
"links": {
    "entities": {
    },
    "documentation": {
    }
}
}

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

Response when no token is provided:

401 Unauthorized
    "message": "No authorization credentials were provided" 
}

 

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).

 

Have more questions? Submit a request

Comments

Powered by Zendesk