Clio API Authentication

What You’re Setting Up

OAuth 2.0 authentication between our middleware and your Clio Manage account. This is how we get authorized access to read and write contacts, matters, activities, and other data in Clio.

This requires a registered app in the Clio developer portal. If you haven’t done that yet, complete the Clio Developer Account guide first.

Prerequisites

• A Clio developer account with a registered application (set that up first)
• Admin access to the Clio Manage account you want to connect
• The Client ID and Client Secret from your registered app

How OAuth 2.0 Works with Clio

Clio uses the standard OAuth 2.0 authorization code flow. Here’s the process:

1. Configure Your App’s Redirect URI

In your app registration on the Clio developer portal, set the redirect URI to the URL we provide. This is where Clio sends the user after they approve access. It must match exactly — Clio rejects the authorization if the redirect URI doesn’t match what’s registered.

2. Set the Required Scopes

Scopes control what the integration can access. For most integrations, we need:

• contacts — read and write contacts and companies
• matters — read and write matters (cases)
• activities — read and write time entries and activities
• calendar_entries — read and write calendar events
• bills — read billing data (if the integration involves invoicing)

We’ll tell you the exact scopes for your project. You configure these in the app registration, and they appear on the approval screen when you authorize.

3. Authorization Code Flow

Here’s the step-by-step:

1. We direct your browser to Clio’s authorization URL with the Client ID, requested scopes, and redirect URI
2. You log into Clio (if not already logged in) and see a screen listing what the app wants to access
3. You click to approve
4. Clio redirects to our server with an authorization code in the URL
5. Our server sends that authorization code (plus the Client ID and Client Secret) to Clio’s token endpoint
6. Clio responds with an access token and a refresh token

You only do steps 1-3 once. After that, everything is automated.

4. Token Refresh Handling

• The access token expires — typically within a few hours
• The refresh token lasts longer, but it also expires if unused for an extended period
• Our middleware automatically uses the refresh token to get a new access token before the old one expires
• If the refresh token itself expires (due to long inactivity or you revoking access), you’ll need to go through the authorization flow again

We monitor token health and will notify you if re-authorization is needed.

5. Send Us Your Credentials

We need your app’s Client ID and Client Secret to initiate the OAuth flow. Send these through the secure link we provide — not via email.

Common Issues

“Redirect URI Mismatch”

The redirect URI in the authorization request must exactly match what’s registered in your Clio app. No trailing slashes, no http vs https differences. If you get this error, double-check the URI in your app settings.

Token Suddenly Stops Working

If the integration loses access unexpectedly, common causes are:

• Someone revoked the app’s access in Clio’s settings
• Your Clio password was changed (may invalidate tokens depending on Clio’s security settings)
• The refresh token expired due to inactivity

The fix is to re-authorize through the OAuth flow.

Wrong Clio Account

If you have access to multiple Clio accounts (firm account, demo account, etc.), make sure you’re logged into the correct one when you approve access. Check the account name in Clio before clicking approve.

Missing Data After Authorization

If we can connect but can’t read certain data, the scopes may be too narrow. We’ll need to update the scopes in the app registration and have you re-authorize.

Next Steps

• Set up custom actions in Clio: Clio Custom Actions
• Learn more about our Clio Integration Services