Skip to main content


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.


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.


client_idYour application key.Yes
response_typeShould be set to code.Yes
redirect_uriThe 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
stateAn 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_declineWhen set to "true", redirects users to the provided redirect_uri when a user declines the app permissions; defaults to "false".No


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

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 = '' + URI.encode_www_form(params)

redirect to(clio_url)

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:

codeAn authorization code that can be exchanged for an access token. The code is valid for 10 minutes.
stateIf 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:

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:

errorSet to access_denied
stateIf 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:

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.


client_idYour application keyYes
client_secretYour application secretYes
grant_typeShould be set to "authorization_code"Yes
codeThe authorization code from step 1Yes
redirect_uriRedirect URI used in the authorization request from step 1Yes


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

curl \
"" \
-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=" \

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 \
"" \
-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.


KeyValue DescriptionRequired
client_idYour application keyYes
client_secretYour application secretYes
grant_typeShould be set to "refresh_token"Yes
refresh_tokenRefresh token obtained during authorizationYes


curl \
"" \
-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.


tokenAccess token to be revokedYes


curl \
"" \
-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:

client_idYour application's key
user_idThe ID of the user whose access token is being deauthorized
access_tokenThe 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

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 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: