Obtaining a Token
API access is controlled with bearer tokens obtained from the OAuth2 provider on behalf of a registered UCF user.
For general background on the OAuth2 process, see http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified#web-server-apps.
- The client redirects the user to OAuth2 provider
The user must be redirected to:
auth.unifiedcompliance.com/authorize
Include the following parameters in the query string:
Parameter Value client_id The client ID of your registered application redirect_uri 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 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. The default and only scope available right now is "read". Currently we restrict access based on a user's groups only, not scopes, so a token grants full access to everything available to the corresponding user. state A secure, random string to protect against attacks like CSRF - The OAuth2 provider redirects the user to the client's redirect_uri
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 - The client obtains a bearer token and refresh token
- Make a POST request with a JSON body to
auth.unifiedcompliance.com/token
Include the following fields:
| Parameter | Value |
| grant_type | Supported types are: authorization_code: use authorization code to obtain bearer and refresh tokens refresh token: use refresh token to obtain new bearer token and optionally a new refresh token if Refresh Token Rotation is enabled. client_credentials: obtain bearer token directly (on behalf of your account as the application owner), no authorization code required |
| code (for "authorization_code" grants only) | The authorization code obtained by the client in step 2 |
| refresh_token (for "refresh_token" grants only) | The refresh token obtained using the "authorization_code" grant |
| client_id | The client ID of your registered application |
| client_secret | The client secret of your registered application - "secret" should hopefully be self-explanatory but treat this as a password and never expose it |
| redirect_uri | 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 |
Example: obtain bearer token using authorization code
Request:
POST /token HTTP/1.1Host: auth.unifiedcompliance.com{"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.1Host: auth.unifiedcompliance.com{"grant_type": "refresh_token","refresh_token": "d60dffd6de7356c49b9ccdb92fb3f8a294981ca9","client_id": "someclient","client_secret": "abcd1234","redirect_uri": "http://clientdomain.com/authorize"}
Response:
200 OK{"access_token": "0303a52830c3bf6213094a29bd2dc2eb24da76f4","expires_in": 3600,"token_type": "bearer","scope": "read"}
Example: obtain a new bearer token using refresh token with Refresh Token Rotation
Request:
POST /token HTTP/1.1Host: auth.unifiedcompliance.com{"grant_type": "refresh_token","refresh_token": "d60dffd6de7356c49b9ccdb92fb3f8a294981ca9","client_id": "someclient","client_secret": "abcd1234","redirect_uri": "http://clientdomain.com/authorize"}
Response:
200 OK{"access_token": "0303a52830c3bf6213094a29bd2dc2eb24da76f4","expires_in": 3600,"token_type": "bearer","scope": "read","refresh_token": "d60dffd6de7356c49b9ccdb92fb3f8afe789f2"}
Example: obtain bearer token using client credentials
Request:
POST /token HTTP/1.1Host: auth.unifiedcompliance.com{"grant_type": "client_credentials","client_id": "someclient","client_secret": "abcd1234"}
Response:
200 OK{"access_token": "0303a52830c3bf6213094a29bd2dc2eb24da76f4","expires_in": 3600,"token_type": "bearer","scope": "read"}
Authenticating With Token
Once you have obtained a valid token, include it in the Authorization header with each request to the API:
Authorization: Bearer <token>
If no token is provided, the request will be refused:
401 Unauthorized{"message": "No authorization credentials were provided"}
Example: successful request
Request:
GET / HTTP/1.1Host: api.unifiedcompliance.comAuthorization: Bearer <token>
Response:
200 OK{"links": {"entities": {},"documentation": {}}}
Other possible sources of errors include an invalid or expired token or malformed Authorization header (e.g. "Bearer" misspelled).