When using Clio's API, there are two layers of permissions to be aware of: access permissions, which relate to what resources your integration has permission to access, and user permissions, which relate to a user's roles within their Clio account.
Though we refer to them as "access permissions" in this document, this concept is interchangable with that of OAuth scopes. If you're unfamiliar with scopes, see oauth.com's article as a starting point.
When you create a new developer application, you must select the access permissions required by your application. You should choose the smallest set necessary for your application to function properly – for example, if you are writing an application which deals with Tasks, you may not need access to records like Bills or Matters.
You can choose between read-only and read/write access for each permission, depending on your needs. Read access allows you to read records for that resource, while write access allows you to read, create, update, and destroy records for that resource.
For example, read access to Matters allows you to perform
GET requests to the Matters endpoint, whether to get a list of matters or get detailed information about a specific matter. It also allows you access to related endpoints, like Practice Areas. Write access to Matters allows you to create a new matter, update an existing matter, or delete a matter. Similarly, you get write access to all related endpoints.
Some endpoints require multiple permissions to access – for example, since Matter Clients and Relationships relate to both Matters and Contacts, accessing them requires both the Matters and Contacts permissions.
When a user enters the authorization flow, they are presented with the list of permissions that your app has requested, which they must accept before your app is granted an access token for that user.
Changing Access Permissions
You may change your application's access permissions at any time. However, once a user has authorized your application, their permissions are fixed, even if their token is refreshed. If you change permissions, you'll need to prompt your users to reauthorize your application, at which point they can view and accept your application's new permissions.
Missing Access Permissions
If you try to access an endpoint without the necessary permissions, The API will return a
403 Forbidden response. The body of the response will contain an
error object with some information about the error, like so:
"message": "User is forbidden from taking that action"
Many of Clio's API endpoints allow access to a resource's associated records. For example, through the Matters endpoint, you can request Activities, Contacts, and so on.
When you request an associated record for which you don't have the necessary permissions to view, Clio will redact most of the association's fields and add a
redacted boolean field onto the nested object. The
redacted field may be requested just like any other field, but it will automatically be added if the object's data has been redacted.
For example, if your application has the necessary permissions to read Matters, but not Contacts, and you make the following request to the API:
All fields except
id will be removed from the nested
client object, and a
redacted property with a value of
true will be added:
In addition to an integration's access permissions, resources in Clio's API may also be restricted due to a user's roles within Clio Manage. For example, if a user does not have the Billing role within Clio, and they attempt to call the Bills endpoint, the API will return a
403 Forbidden response.
Permissions and Associations
If a record has associations that protected by Clio's user permissioning system, we will remove requested fields, and add a
redacted boolean field onto the object. The
redacted field may be requested just like any other field, but it will automatically be added if we have redacted the object.
For example, if the user does not have the Billing role and attempts to access Bill information via an association from another endpoint such as Activities, like so:
The response will look as follows:
In most cases, the only visible information for a redacted object will be its
id field. However, certain resources and endpoints will behave differently. Their behaviour is listed below.
A user requesting a Matter for which they do not have permission to access can view the Matter's
For example, if a user requests information about a Task's associated Matter which they do not have permission to view, like so:
The response will look as follows:
"display_number": "00001-Luettgen, Marks and Wilkinson",
Visibility of fields on Activity records can be limited via the "Billing Rate Visibility" and "Activity Hours Visibility" settings.
Billing Rate Visibility
The "Billing Rate Visiblity" setting affects activities of the type
If the user’s rate visibility is set to "Own", the
total fields of
TimeEntry records that other users have created are removed from the response, and the
redacted field is set to
If the user’s rate visibility is set to "None", the
total fields of all
TimeEntry are removed from the response, and the
redacted field is set as
An example request would be:
A redacted response would return as follows:
Activity Hours Visibility
The "Activity Hours Visiblity" setting affects whether a user can view hours on activities of type
If the permission is set to “Own and when acting as a matter’s Responsible Attorney”, the user may receive redacted values for time-related fields or be unable to update those fields.
This affects all endpoints that return
Activity records of type
TimeEntry, either directly (via the
activities endpoint) or as a nested object. The full list of endpoints and behaviour is below:
|activities||GET||activity (type: TimeEntry)||The listed fields will be |
|activities||PATCH||activity (type: TimeEntry)||If a user attempts to update any of the listed fields on an activity that has a quantity field redacted for them, they will receive a |
|calendar_entries||GET||time_entries (nested property)||same as activities GET requests above||same as activities GET requests above|
|communications||GET||time_entries (nested property)||same as activities GET requests above||same as activities GET behavior above|
|notes||GET||time_entries (nested property)||same as activities GET requests above||same as activities GET behavior above|
|tasks||GET||time_entries (nested property)||same as activities GET requests above||same as activities GET behavior above|