Permissions

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.

Access Permissions

info

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 to generate new access and refresh tokens that will allow your app to access to the newly requested scopes.

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:

{
  "error": {
    "type": "ForbiddenError",
    "message": "User is forbidden from taking that action"
  }
}

Associations

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:

https://app.clio.com/api/v4/matters/1?fields=id,display_number,client{id,name}

All fields except id will be removed from the nested client object, and a redacted property with a value of true will be added:

{
  "data": {
    "id": 1,
    "display_number": "00001-Marquardt-Walter",
    "client": {
      "id": 1,
      "redacted": true
    }
  }
}

User Permissions

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:

https://app.clio.com/api/v4/activities/15?fields=id,bills{id,number}

The response will look as follows:

{
  "data": {
    "id": 15,
    "bill": {
      "id": 527,
      "redacted": true
    }
  }
}

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.

Matters

A user requesting a Matter for which they do not have permission to access can view the Matter's id and display_number fields.

For example, if a user requests information about a Task's associated Matter which they do not have permission to view, like so:

https://app.clio.com/api/v4/tasks/16?fields=id,matter{id,display_number,client}

The response will look as follows:

{
  "data": {
    "id": 16,
    "matter": {
      "id": 1,
      "display_number": "00001-Luettgen, Marks and Wilkinson",
      "redacted": true
    }
  }
}

Activities

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 TimeEntry.

If the user’s rate visibility is set to "Own", the price and total fields of TimeEntry records that other users have created are removed from the response, and the redacted field is set to true

If the user’s rate visibility is set to "None", the price and total fields of all TimeEntry are removed from the response, and the redacted field is set as true.

An example request would be:

https://app.clio.com/api/v4/activities?fields=id,quantity,price,total

A redacted response would return as follows:

{
  "data": {
    "id": 16,
    "quantity": 2197,
    "redacted": true
  }
}

Activity Hours Visibility

The "Activity Hours Visiblity" setting affects whether a user can view hours on activities of type TimeEntry.

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:

Endpoint	HTTP Method	Object	Fields	Description
activities	GET	activity (type: TimeEntry)	quantity rounded_quantity rounded_quantity_in_hours quantity_in_hours total non_billable_total	The listed fields will be null and a quantity_redacted: true field will be added to the response body.
activities	PATCH	activity (type: TimeEntry)	quantity user_id	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 403 Forbidden error in response.
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