Authorization

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.

  1. 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
  2. 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
  3. 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
    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.1
    Host: auth.unifiedcompliance.com
    {
      "grant_type": "authorization_code",
      "code": "f140088c4155ac86d9d57aa324a30607e0cfc023",
      "client_id": "someclient",
      "client_secret": "abcd1234",
    }
    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
    {
      "grant_type": "refresh_token",
      "refresh_token": "d60dffd6de7356c49b9ccdb92fb3f8a294981ca9",
      "client_id": "someclient",
      "client_secret": "abcd1234",
    }
    Response:

    200 OK
    {
        "access_token": "0303a52830c3bf6213094a29bd2dc2eb24da76f4",
        "expires_in": 3600,
        "token_type": "bearer",
        "scope": "read"
    }
    Example: obtain bearer token using client credentials

    Request:
    POST /token HTTP/1.1
    Host: 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.1
Host: api.unifiedcompliance.com
Authorization: Bearer <token>

Response:

200 OK
{
    "links": {
        "entities": {
            "_href": "https://api.unifiedcompliance.com/entities"
        },
        "documentation": {
            "_href": "https://api.unifiedcompliance.com/documentation"
        }
    }
}
 
 

Other possible sources of errors include an invalid or expired token or malformed Authorization header (e.g. "Bearer" misspelled).

Have more questions? Submit a request

Comments

Powered by Zendesk