Authorization

Authorization is the process by which a Clio user grants permission for your application to access their data. In order to use the Clio API, your application must first obtain authorization from the user. Clio implements the OAuth 2.0 specification.

When a user successfully authorizes your application, your application is granted an access token representing that user. This access token must be included in all requests to the Clio API.

info

The first step in authorizing users is to create a new application in your Clio developer account. This account will contain the key and secret values you need to follow the OAuth flow described below. If you haven't created an application, see our Developer Applications guide, then return here when finished!

Authorization Code Flow

The Clio API supports the Authorization Code grant type. In this flow, the user is sent from your application to a confirmation screen in Clio where the user authorizes your application to access their Clio data. The user is then redirected to your application with an authorization code attached. Your app can then exchange this code for an access token associated with the user. With this token, you're able to call the Clio API to access that user's data.

Below, we'll walk through the steps needed to complete the authorization flow.

Step 1: Get authorization code

First, your application needs to make a GET request to Clio to kick off the authorization flow. When building a web application, this is usually done by redirecting a user to Clio's authorize endpoint, passing certain values as query parameters.

Parameters

Key	Value	Required?
client_id	Your application key.	Yes
response_type	Should be set to `code`.	Yes
redirect_uri	The URL to redirect to after the user grants authorization to your app. The URL must match one of the redirect URLs specified in your application settings. See the applications doc for more information.	Yes
state	An opaque value used to maintain state between the request and the callback. See The OAuth 2.0 RFC for more information.	No, but recommended
redirect_on_decline	When set to "true", redirects users to the provided redirect_uri when a user declines the app permissions; defaults to "false".	No

Example

Below is an example of the URL your app would construct and request:

https://app.clio.com/oauth/authorize?response_type=code&client_id=fzaXZ...i7F96&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&state=xyz

The following Ruby code sample using Sinatra demonstrates constructing the URL and initiating the authorization flow:

require 'sinatra'

get '/clio_authorization' do
  state = SecureRandom.hex

  params = {
    response_type: 'code',
    client_id: 'fzaXZ...i7F96',
    redirect_uri: url('/auth_callback'),
    state: state,
    redirect_on_decline: true
  }

  clio_url = 'https://app.clio.com/oauth/authorize?' + URI.encode_www_form(params)

  redirect to(clio_url)
end

Grant Approved

If the user approves your application's request, Clio will redirect them to the redirect_uri specified in your initial request. The callback will contain between one and two query parameters:

Key	Value
code	An authorization code that can be exchanged for an access token. The code is valid for 10 minutes.
state	If a `state` parameter was provided to the `/authorize` endpoint, the callback will include the same parameter here.

A sample callback URL for an approved grant is below:

http://yourapp.com/callback?code=s9jG...3AEO&state=xyz

Grant Declined

If the user declines your application's request access, they will be redirected to a Clio error page with a 400 response code. If you set the redirect_on_decline parameter to true in the request to the /authorize endpoint, Clio will redirect the user to the provided redirect_uri with the following parameters:

Key	Value
error	Set to `access_denied`
state	If a `state` parameter was provided to the `/authorize` endpoint, the callback will include the same parameter here.

A sample callback URL for a declined grant is below:

http://yourapp.com/callback?error=access_denied&state=xyz

Step 2: Exchange the authorization code for an access_token

After receiving an authorization code from Clio, your application can make a POST request to Clio to exchange the code for an access token. For Clio to verify the grant request, you must include your application's key and secret, as well as the redirect_uri from the code request, in the POST body.

Note that this request must specify the application/x-www-form-urlencoded content-type in an HTTP header.

Parameters

Key	Value	Required
client_id	Your application key	Yes
client_secret	Your application secret	Yes
grant_type	Should be set to "authorization_code"	Yes
code	The authorization code from step 1	Yes
redirect_uri	Redirect URI used in the authorization request from step 1	Yes

Example

A sample cURL POST request to get an access token would look as follows:

curl \
    "https://app.clio.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=fzaXZ...i7F96" \
    -d "client_secret=xVp5w...V876v" \
    -d "grant_type=authorization_code" \
    -d "code=s9jG...3AEO" \
    -d "redirect_uri=http://yourapp.com/callback" \

A sample JSON response payload for the above request would look as follows:

{
  "token_type": "bearer",
  "access_token": "WjR8HL...dU2ul",
  "expires_in": 604800,
  "refresh_token": "5A0Dd...Gvx7e"
}

The access token you've received can now be used to make requests to the Clio API. The refresh token can be used to refresh an expired access token.

Using an Access Token

When making an API request, include the access_token from step 2 in an Authorization header (Authorization: Bearer access_token).

curl \
    "https://app.clio.com/api/v4/users/who_am_i" \
    -H "Authorization: Bearer WjR8H...dU2ul"

Below is a sample JSON response payload for the above request:

{
  "data": {
    "id": 123456789,
    "etag": "\"1514daee6390dbbb6a68f6d0d2c36334\"",
    "name": "Demo User"
  }
}

If your access token is expired, you will receive a 401 Unauthorized response. See "Refreshing an Access Token" below to learn how to refresh an expired access token.

Refreshing an Access Token

Access tokens have a limited lifespan and will eventually expire. When they expire, a new access token can be granted using the refresh token provided during the authorization flow.

Refresh tokens do not expire; as a result, they should be encrypted and stored securely.

For background on the use of refresh tokens, see Understanding Refresh Tokens.

Parameters

Key	Value Description	Required
client_id	Your application key	Yes
client_secret	Your application secret	Yes
grant_type	Should be set to "refresh_token"	Yes
refresh_token	Refresh token obtained during authorization	Yes

Example

curl \
    "https://app.clio.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=fzaXZvrLWZX747wQQRNuASeVCBxaXpJaPMDi7F96" \
    -d "client_secret=xVp5wAX05g1oDjV5astg2KZIZ85NX31FKTPV876v" \
    -d "grant_type=refresh_token" \
    -d "refresh_token=5A0Ddf2RSt75v1VQcCoTB9rImRydF9yXA0gGvx7e"

Below is a sample JSON response containing a refreshed access token:

{
  "token_type": "bearer",
  "access_token": "rFlGXgfqh1e8yBIGGh4jSMaJAuOZb4Bo4VKEG6wK",
  "expires_in": 604800
}

Deauthorizing an access token

An access token can be deauthorized in one of two ways:

The user has revoked access to your application from within Clio Manage.
Your application requests to deauthorize a user's access token.

When a user revokes access to your application from within Clio, access tokens and refresh tokens for that user will be deauthorized. If your application requests the deauthorization, only the supplied access token will be deauthorized.

To request deauthorizing an access token from within your app, you need to make an authorized POST request to /oauth/deauthorize.

Parameters

Key	Description	Required
token	Access token to be revoked	Yes

Example

curl \
    "https://app.clio.com/oauth/deauthorize" \
    -H "Authorization: Bearer WjR8HLdo847Z8kdfUtewJpCvkRX4JYLCIF2dUUul" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "token=WjR8HLdo847Z8kdfUtewJpCvkRX4JYLCIF2dUUul"

The response will be a 200 OK with no body.

Deauthorization Callback

In your application settings in Clio Manage, you can set a deauthorization callback URL. If this is set, when an access token is deauthorized (whether by your application or from within Clio Manage), Clio will make a POST request to the specified URL.

TK screenshot

The request will include a JSON object containing the following fields:

Key	Description
client_id	Your application's key
user_id	The ID of the user whose access token is being deauthorized
access_token	The access token being deauthorized. If the user initiatiated the access being revoked, the value of this field will be `"all"`

Mobile and Desktop Applications

If you are building a desktop or mobile application, there are some changes to the authorization workflow that you'll need to be aware of. Note that this section is not a comprehensive guide – if you run into challenges with the authorization flow in desktop or mobile apps, please reach out to us at api@clio.com.

Changes to Step 1

To capture the redirects that occur in the authorization flow, you may need to perform the authorization requests inside a "web view" in your application. The details for this vary by platform; refer to your OS or development platform's documentation for details.

Additionally, since desktop or mobile apps may not have a web server to redirect to, you can use https://app.clio.com/oauth/approval for your redirect_uri. This is a special authorized redirect URI that embeds the authorization code in both the URL and page title, which your application can then retrieve.

If the grant is approved, the authorization code will appear in the URL in the code query parameter of the URL. The page title will be in the format Success code=5IzZeWL2OmZUxGOGO4WE.

If the grant is denied, the error will appear in the URL in the error query parameter. The page title will be in the format Failure error=access_denied.

Intercepting this redirect to retrieve the authorization code will vary from platform to platform. Here are some references to get you started:

.NET: WebBrowser.Navigate.
iOS/OSX: webView:decidePolicyFor:decisionHandler on the WKNavigationDelegate.
Android: WebViewClient event onPageStarted (android.webkit.WebView, java.lang.String, android.graphics.Bitmap).

Authorization

Authorization Code Flow​

Step 1: Get authorization code​

Parameters​

Example​

Grant Approved​

Grant Declined​

Step 2: Exchange the authorization code for an access_token​

Parameters​

Example​

Using an Access Token​

Refreshing an Access Token​

Parameters​

Example​

Deauthorizing an access token​

Parameters​

Example​

Deauthorization Callback​

Mobile and Desktop Applications​

Changes to Step 1​

Authorization Code Flow

Step 1: Get authorization code

Parameters

Example

Grant Approved

Grant Declined

Step 2: Exchange the authorization code for an access_token

Parameters

Example

Using an Access Token

Refreshing an Access Token

Parameters

Example

Deauthorizing an access token

Parameters

Example

Deauthorization Callback

Mobile and Desktop Applications

Changes to Step 1