DEV Community: Drew-Opexcell

Why your Clio token stopped working

Drew-Opexcell — Tue, 21 Jul 2026 21:21:50 +0000

If your Clio integration started returning 401 and you are trying to work out why, the first question is not about your code. It is which of Clio's two OAuth systems you are on, because they have different rules and most advice on the internet does not say which one it is describing.

There are two, and they are not interchangeable

Clio Manage is the older one. OAuth at app.clio.com/oauth, API at app.clio.com/api/v4.

Clio Platform is the newer one, covering Grow and the lead inbox among others. OAuth at auth.api.clio.com/oauth, API at api.clio.com.

They differ on essentially every point that matters when a token dies.

	Manage	Platform
Access token lifetime	2,592,000s, 30 days	86,400s, 24 hours
Refresh token expiry	Documented as none	No time expiry, but rotates
Refresh token rotation	Not documented, and the refresh sample returns no new refresh token	Documented: rotates on every use, previous one revoked
Revocation endpoint	`POST app.clio.com/oauth/deauthorize`, Bearer auth	`POST auth.api.clio.com/oauth/revoke`, Basic auth

Treat the lifetime row as the documented default rather than a constant. Honour the expires_in you get back on each response instead of hardcoding 30 days, because there are field reports of accounts issuing much shorter access tokens, and a hardcoded assumption fails in a way that looks exactly like revocation.

That rotation row is the one that decides your debugging. On Platform, every refresh gives you a new refresh token and kills the old one, so failing to persist the new value out of each response leaves you holding a dead token the next time you try. Clio's docs say it directly: store the new refresh token returned in each response.

On Manage, the documented behaviour is a long-lived refresh token that does not expire and is not replaced. Their refresh response sample does not even include a refresh_token field. So on Manage, a token that suddenly stops working usually points somewhere else: revocation, or the wrong region.

The region trap

Clio runs four separate instances, and this is the one that turns a five minute fix into an afternoon because nothing about the error says "region."

Region	Manage API	Platform OAuth
US	`app.clio.com/api/v4`	`auth.api.clio.com`
EU	`eu.app.clio.com/api/v4`	`eu.auth.api.clio.com`
Canada	`ca.app.clio.com/api/v4`	`ca.auth.api.clio.com`
Australia	`au.app.clio.com/api/v4`	`au.auth.api.clio.com`

Clio's documentation states that a token issued in one region is not valid against another region's API. So if you built against app.clio.com because that is what every tutorial uses, and you have just onboarded a firm on the Australian instance, nothing is wrong with the token. You are asking the wrong server.

Do not stop at swapping the hostname, because it will fail again. Clio requires a separate developer application in each region, which means a separate client_id and client_secret per region as well. Supporting a second region is a registration exercise, not a config change, and finding that out one failure at a time is the slow way.

Revocation is asymmetric, and it matters

This is the detail most likely to explain a chain that died without anyone touching the code.

Clio's Manage documentation draws a distinction that is easy to skim past: when the user revokes access to your application from inside Clio, both access tokens and refresh tokens for that user are deauthorized. When your application requests the deauthorization, only the supplied access token is deauthorized.

So a firm administrator clicking "disconnect" in their Clio settings takes out your refresh token too, permanently, and your integrations will fail on their next call with nothing in your logs explaining why. Your own deauthorize call does something much narrower.

Clio also offers a deauthorization callback URL you can set on the app, which POSTs client_id, user_id and access_token when access is revoked, and sends the literal string all for the access token when the user initiated it. If you run anything in production against Clio, set that callback.

There is no API path back

Once a grant is revoked, the documented recovery is that the user re-authorizes through the browser. There is a deauthorize endpoint for ending access and nothing for restoring it.

Recovery requires a specific human with access to the Clio account, in a browser, doing an OAuth flow. If that person is in a hearing, your integrations stay down until they are out. Two things worth having ready before you need them: a written re-authorization procedure that somebody other than the original developer can follow, including the exact scopes to request, because re-authorizing with fewer scopes brings half your integrations back in a subtler kind of broken; and alerting that fires on the token failure itself rather than on the downstream symptoms.

What we run, and what it is for

Several scheduled jobs sharing one stored Clio connection is a fragile shape whichever system you are on, because a rotating system punishes any two jobs that refresh at once, and every system punishes a stale cached token.

Two measures, and they work together. Refresh proactively on a schedule so nothing is ever near expiry and on-demand refreshes almost never fire. And before any worker calls the token endpoint, have it re-read the stored token and stand down if a sibling already refreshed, using the persisted refresh token rather than whatever it cached at startup. That second detail matters more than it looks: a long-running process holding a token it read hours ago is exactly the thing that submits a stale one.

If you want a hard guarantee rather than a small probability, a database advisory lock around the refresh gives you a single writer. We have not needed it on top of the two measures above.

One diagnostic worth keeping: if every integration fails at the same timestamp, that is a shared-credential problem, not five coincidences. It rules out a lot quickly.

Lifetimes, rotation behaviour, region hosts and the revocation asymmetry above are from Clio's developer documentation for Clio Manage and Clio Platform, checked July 2026. Clio does not publish the error body its token endpoint returns for an invalid refresh token, so this page does not guess at one. The refresh pattern in the last section is what we run in production. If Clio changes any of this, believe their docs over this page.

How to apply a Clio task template to a matter through the API

Drew-Opexcell — Tue, 21 Jul 2026 21:21:21 +0000

There are two versions of this job and they have different answers. Most of the confusion, including ours, comes from assuming they are the same thing.

Applying a whole template list to a matter

Clio's interface has a button for this, and the natural assumption is that there is a matching endpoint on the task template resource. There is not. Nothing under /task_template_lists will assign anything to a matter, and no path in Clio's spec contains "apply".

It is done from the matter instead. Both POST /matters.json and PATCH /matters/{id}.json accept a nested array:

task_template_list_instances[]:
  task_template_list : { id }   required on POST
  assignee_id        : the user the list is assigned to
  notify_assignees    : whether assignees get notified
  due_at             : ISO-8601 date (format: date, not date-time)

Those are the only two operations in the API that accept it. Note the asymmetry: on POST /matters.json the task_template_list object is required, and on PATCH /matters/{id}.json the item schema marks nothing as required at all.

POST /task_template_lists/{id}/copy.json exists and sounds like the thing you want. It is not. It duplicates a list into another list, takes name, description and practice_area (all optional), and has no matter parameter.

The two problems that will actually cost you time

Instances are write-only. task_template_list_instances appears in those two request bodies and nowhere in the matter response schema. So there is no documented way to ask "does this matter already have the list on it?" You verify by fetching /tasks.json filtered to the matter and matching on names, which is uglier than it sounds and is most of the reconciliation work.

Which makes idempotency your problem. If your automation fires the PATCH twice, nothing in the API stops you assigning the checklist twice. For anything triggered off matter creation or a stage change, decide up front how you detect an already-applied list, because the readback above is the only tool you have.

Between them, those two are roughly half the build. Scope accordingly: with the trigger, the guard and the reconciliation this is a two to four day job. It looks like an afternoon.

Due dates, and what `due_at` actually seeds

Task template due dates are a chain, not a flat set of offsets. Each template carries cascading, cascading_source (the parent template it derives from), cascading_offset, cascading_offset_polarity (before or after the parent) and cascading_offset_type (CalendarDays, CalendarWeeks and so on). Templates with cascading: false carry no offset at all.

The due_at you pass on the instance seeds the root of that chain, and Clio resolves the rest.

Worth being precise about the consequence, because it is easy to overstate: you do not lose the cascade by building tasks yourself. POST /tasks.json exposes the same five fields, including cascading_source, described as the parent task used to determine the cascaded task's due_at. So you can rebuild the chain manually by pointing each task at the one before it.

The honest difference is effort and fidelity, not capability. Using the instance means Clio resolves the chain from one date you supply. Building by hand means you reconstruct the parent relationships yourself and keep them correct as the template list changes. That is a real reason to prefer the instance and it is not the same as "you cannot do it."

Creating one task from one template

Different job. Here you want a single task created from a single template, which is what you need when something in your own workflow decides a specific task is due.

POST /tasks.json has no template field of any kind. Its required fields are name, description and assignee, so nothing is inherited for you. Read the template and pass the fields explicitly:

GET  /api/v4/task_templates/{id}.json?fields=id,name,description,priority

POST /api/v4/tasks.json
{
  "data": {
    "matter":      { "id": <MATTER_ID> },
    "name":        "<template name>",
    "description": "<template description>",
    "priority":    "<template priority>",
    "assignee":    { "id": <USER_ID>, "type": "User" }
  }
}

Three things worth knowing before you build it:

description is required, and templates can have an empty one. Copying an empty description straight across fails the call, so you need a fallback rather than passing through whatever the template holds. This one cost us a production run.

The assignee does not carry itself. We resolve it from the matter's responsible_staff, falling back to responsible_attorney, and throw rather than guess when the matter has neither. Guessing is worse than failing loudly, because a task assigned to the wrong person looks done.

If you list templates, get the pagination right. /task_templates.json uses cursor paging and returns meta.paging.next as a full URL, not a token to append. Cursor paging also requires ordering by order=id(asc); without it you silently fall back to offset paging, which is capped at 10,000 records. Page size is 200, so this matters at real volume rather than on a single practice area's list.

Which one you want

If your trigger is "a matter of this type was created and should get its standard checklist," you want the list instance on the matter, passed at creation so the chain anchors correctly.

If your trigger is something your own code decided, a document arrived, a stage changed, a deadline moved, you want the single-task path, because there is no list involved and you are creating one task on purpose.

The expensive mistake is finding only the second path, concluding lists cannot be assigned through the API at all, and rebuilding every checklist task by task. That happens because the obvious place to look has nothing in it.

Endpoint shapes, field names and required flags above are from Clio's published API reference and OpenAPI spec for Clio Manage v4, checked July 2026. The empty-description failure and the assignee handling are from our own production integration. Clio does not publish the error string for the first of those, so it is reported here as our observation rather than as documentation. If Clio changes any of this, believe the reference over this page.