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 Platform API, your application must first obtain authorization from the user. The Clio Platform API implements the OAuth 2.0 specification using the Authorization Code grant type.

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 Platform API.

info

The first step in authorizing users is to create a new developer application in the Clio Developer Portal. This will provide you with the client_id and client_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

In the Authorization Code 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 Platform API to access that user's data.

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.

The authorization endpoint is https://grow.clio.com/oauth/authorize. The following query parameters must be added to the URL:

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.	Yes
scope	A list of scopes that your app is requesting, separated by spaces. See the permissions documentation for more information.	Yes
state	An opaque value used to maintain state between the request and the callback. This parameter helps prevent CSRF attacks. See The OAuth 2.0 RFC for more information.	No, but recommended

Example

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

https://grow.clio.com/oauth/authorize?response_type=code&client_id=fzaXZ...i7F96&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=lead_inbox_read%20lead_inbox_write&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'),
    scope: 'lead_inbox_read lead_inbox_write',
    state: state
  }

  clio_url = 'https://grow.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 for access, they will be redirected to a Clio error page with a 400 response code.

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: The Content-Type header of this request must be set to application/x-www-form-urlencoded.

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	The 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://grow.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": 2592000,
  "refresh_token": "5A0Dd...Gvx7e",
  "created_at": 1234567890,
  "scope": "lead_inbox_read,lead_inbox_write"
}

The access token you've received can now be used to make requests to the Clio Platform 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://api.clio.com/grow/contacts" \
    -H "Authorization: Bearer WjR8H...dU2ul"

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 of 30 days 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.

Parameters

Key	Value	Required?
client_id	Your application key.	Yes
client_secret	Your application secret.	Yes
grant_type	Should be set to refresh_token.	Yes
refresh_token	The refresh token provided during the initial token grant.	Yes

Example

curl \
    "https://grow.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": 2592000,
  "refresh_token": "newRefreshToken123...",
  "created_at": 1234567890,
  "scope": "lead_inbox_read,lead_inbox_write"
}

Note: The response will contain the same properties as listed in Step 2's response, above. Both the access token and refresh token are regenerated as part of this process.

Revoking an access token

Your app should provide users with a way to revoke their access token and disconnect the integration from Clio. To request revoking an access token from within your app, you need to make a POST request to https://grow.clio.com/oauth/revoke.

Headers

The request should have the following headers:

• Content-Type: application/x-www-form-urlencoded
• Authorization: You must use Basic auth, with a Base64-encoded string in the format of client_id:client_secret.

For example, if your client ID is abc123 and your client secret is xyz789, the base64 encoding of abc123:xyz789 is YWJjMTIzOnh5ejc4OQ==, and your header would be:

Authorization: Basic YWJjMTIzOnh5ejc4OQ==

Parameters

Key	Description	Required?
token	The access token to be revoked	Yes

Example

curl \
    "https://grow.clio.com/oauth/revoke" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Basic YWJjMTIzOnh5ejc4OQ==" \
    -d "token=WjR8HLdo847Z8kdfUtewJpCvkRX4JYLCIF2dUUul"

The response will be a 200 OK with no body if the token is successfully revoked.

Proof Key for Code Exchange (PKCE)

The Clio Platform API supports PKCE (Proof Key for Code Exchange) for enhanced security, particularly for public clients (such as mobile and desktop applications) that cannot securely store a client secret.

When to Use PKCE

PKCE is recommended for:

• Desktop applications
• Single-page applications (SPAs)
• Any application where the client secret cannot be securely stored

How PKCE Works

PKCE adds an extra layer of security by generating a code verifier and code challenge during the authorization flow:

1. Code Verifier: A cryptographically random string (43-128 characters) that your application generates
2. Code Challenge: A SHA256 hash of the code verifier, base64url-encoded
3. Code Challenge Method: The method used to generate the challenge (always S256 for SHA256)

Step 1: Generate Code Verifier and Challenge

Before initiating the authorization flow, your application should generate:

// Example in JavaScript
const codeVerifier = generateRandomString(128); // 43-128 characters
const codeChallenge = base64UrlEncode(sha256(codeVerifier));
const codeChallengeMethod = 'S256';

Step 2: Include PKCE Parameters in Authorization Request

Add the following parameters to your authorization request:

Key	Value	Required?
code_challenge	The base64url-encoded SHA256 hash of the code verifier	Yes (if using PKCE)
code_challenge_method	Should be set to S256	Yes (if using PKCE)

Example Authorization Request with PKCE

https://grow.clio.com/oauth/authorize?response_type=code&client_id=fzaXZ...i7F96&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=lead_inbox_read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=xyz

Step 3: Exchange Authorization Code with Code Verifier

When exchanging the authorization code for an access token, include the code_verifier parameter:

Key	Value	Required?
code_verifier	The original code verifier that was used to generate the code challenge	Yes (if using PKCE)

Example Token Exchange with PKCE

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

Note: When using PKCE, you do not need to include the client_secret in the token exchange request. This makes PKCE ideal for public clients that cannot securely store secrets.

Enabling PKCE for Your Application

To use PKCE with your application, you must enable PKCE support in your application settings in the Clio Developer Portal. When creating or editing your application, check the "Support Proof of Key Code Exchange (PKCE) OAuth2 flow" option.