1. Docs
  2. When a Change Takes Effect

When a Change Takes Effect

How soon a revoked credential, a changed role or a passing assignment window reaches Canopy's own routes, an API guarded by the SDK, and an application that reads its tokens itself.

Three places answer for access

A change to someone's access is written to Canopy at once. What differs is how soon each place that answers may this person do this? learns of it, and that depends on where the answer comes from:

Canopy's own routes (the API, the hosted pages and POST /api/v1/permissions/evaluate) read identities, memberships and assignments from the database on every request. Nothing is cached between requests.An API guarded by the SDK verifies each access token in its own process and answers checks from grants it holds for 60 seconds by default, never longer than 5 minutes. See Authorization Caching.An application that reads its tokens itself trusts each access token until it expires: 15 minutes by default for a person, 5 minutes for a machine client. Whatever the token says, including a permissions claim or organization claims, holds until then.

How soon each change lands

Each row is a change; each column is one of the places above: Canopy for its own routes, With the SDK for an API the SDK guards, and Token only for an application that reads its tokens itself. Next request means the request after the change is answered with it. At expiry means a token already issued keeps working until it expires, shown at the Environment's default lifetime. Next token means the change appears in the claims of the next token issued, at the latest when the current one expires.

Change Canopy With the SDK Token only
An identity deactivated or removed from the Environment Next request Within 60 seconds At expiry (15 minutes)
A session signed out or revoked Refresh: at once. Token: at expiry (15 minutes) At expiry (15 minutes) At expiry (15 minutes)
A machine client disabled or deleted No new token: at once At expiry (5 minutes) At expiry (5 minutes)
A machine client's secret rotated Old secret: after 24 hours, or at once At expiry (5 minutes) At expiry (5 minutes)
A role, assignment, membership or node changed Next request Within 60 seconds, or at once with invalidate Next token (15 minutes)
A deny created or deleted Next request Within 60 seconds, with an SDK that reads model version 2 Next token (15 minutes)
An assignment window opening or closing On time On time Next token (15 minutes)

A deactivated or removed identity reaches the SDK when it next reads that identity's grants, which come back empty. The SDK holds no answer past an assignment's next window edge, so a window opens and closes on time there too. An API key is checked on every request, so a revoked, rotated or expired key is refused from the next one. The SDK's token verifier allows 60 seconds of clock leeway on a token's expiry by default, so add that to any token lifetime above.

Three kinds of change

Every row is one of three kinds, each with its own bound:

A credential (an identity, a session, a machine client): Canopy refuses its next refresh or mint at once, and refuses a deactivated or removed identity on its own routes from the next request. Otherwise a token already issued lives on until it expires, so the access-token lifetime is the bound: 15 minutes for a person and 5 minutes for a machine client by default.An authorization change (an assignment, a role, a membership, the tree, a deny): immediate on Canopy's routes, and at most the SDK's cache window everywhere the SDK answers, 60 seconds by default. Immediate in a process that clears its cache when it hears of the change.A scheduled boundary (an assignment's effective_from or effective_to): on time for Canopy and the SDK, which both read the window itself. The assignment.activated or assignment.expired webhook event follows within 1 minute, for anything else you keep.

Making it faster

The bounds above are the most a change waits. To close them sooner:

Clear the SDK's cache when access changes. Call invalidate(identityId) when your backend changes someone's access, or from a webhook for assignment.created, assignment.updated, assignment.removed, identity.status_set, identity.env_membership.removed or organization.member.removed. Call invalidate() with no argument for a change whose reach you cannot name: a role's permissions edited, a role deactivated, a node moved.Shorten the token lifetimes. The Environment's access-token lifetime can be as short as 60 seconds, and its machine-token lifetime as short as 60 seconds. That is the bound on how long an issued token outlives a revoked credential on an API that verifies it locally.End a rotated secret at once. Rotate a machine client's secret with expire_previous: "now" when the old one is compromised, rather than letting it work for 24 hours.Catch up after a restart. Read the change feed, GET /api/v1/changes, from the last cursor you kept, to apply the events a process missed while it was down.

A webhook delivery reaches one of your processes. invalidate clears that process's cache only, so across several instances the cache window stays the guarantee unless you pass the event to every instance yourself.

Next Step

How the SDK answers a check from its own memory, what it holds to do it, and how to tune its window.

Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy