Having a seat in the access group is only half the picture. This article explains the runtime mechanics — how Dockli turns a seat into working access, how the AI features are gated, and how expiry, suspension, cancellation, and renewal behave.
Sign-in and heartbeat checks
The Dockli app calls the licensing service in two situations:
- At sign-in — to establish whether the user holds a seat and what their plan allows.
- On a heartbeat — periodically while the app runs, so a change (a reclaimed seat, an expired term, a suspended tenant) takes effect without waiting for the user to sign out and back in.
Each call returns the user’s current seat status, plan tier, feature set, and a signed entitlement token.
The entitlement token
The licensing service returns a signed entitlement token — an RS256-signed JWT valid for 24 hours — carrying the tenant, the user, the plan tier, and the enabled features. The app caches this token and attaches it to AI requests.
At the secure API gateway (Azure API Management), that token is what gates the AI features: the gateway verifies the signature against Dockli’s published keys and only lets the request through if the token grants the ai feature. In other words, AI access is enforced server-side by the signed token, not just hidden in the UI.
The app refreshes the token when it’s missing or older than about an hour, so a cancelled or expired seat stops working server-side within that refresh window even if the on-screen state is briefly stale.
Tier drives features
Essential carries the documents feature — the full File Explorer experience without AI. Spark carries ai,documents — everything, including Ask Dockli. When you change tier, the next token refresh carries the new feature set. See Plans.
Seat statuses
Every entitlement check resolves to one status:
| Status | Meaning |
|---|---|
held | The user holds a seat — full access for their tier. |
no-seat | Licensed tenant, but the user isn’t in the group or all seats are taken. No access until a seat is available. |
unlicensed | No active licence for this tenant (e.g. consent not completed, or the org isn’t provisioned). |
expired | The licence term has ended. Access is gated until the term is renewed. |
service-unavailable | The licensing service couldn’t be reached and there’s no usable cached answer. The app shows a Retry rather than a hard denial — this is a service issue, not a real “no seat”. |
Grace window and cold-start behavior
The licensing service runs on serverless Azure infrastructure, so the first call after an idle period or a deploy can take several seconds while the App Service warms up and the database wakes from auto-pause. Dockli is built to ride that out so a cold start never locks anyone out:
- 20-second timeout with a retry. The app allows up to 20 seconds and makes a second attempt after a brief pause, so a routine cold start doesn’t get mistaken for an outage.
- A 10-day grace window. The app caches the last good “licensed” answer and, if the licensing service is briefly unreachable, keeps serving that answer for up to 10 days. A short outage — or a cold start — therefore never interrupts a working user.
Grace protects working users, not new ones
The grace window replays a user’s last good answer. It keeps someone who already had a seat working through a blip; it can’t grant access to someone who never successfully checked in. If the service is unreachable and there’s no cached answer, the user sees service-unavailable with a Retry.
Expiry, suspension, and cancellation
Access is gated the moment a licence stops being Active — enforced at the next sign-in or heartbeat, and server-side within the token refresh window:
- Expiry. When the term end passes, the status becomes
expired. Renew the term to restore access. - Suspension. The Dockli team can suspend a tenant (for example, a billing hold). Suspended tenants have no active licence, so every user is gated until reactivated.
- Cancellation. Ending the agreement cancels the tenant and its licences. As with suspension, all users are gated at their next check.
Because these all take the licence out of the Active state, they take effect quickly and don’t require touching individual users.
Renewals
Renewing extends the licence term. When an expired licence’s term is pushed back into the future, it returns to Active and users regain access at their next check — no re-consent and no re-install. Seat assignments and group membership are preserved across a renewal.
Where to go next
- Access groups and seats — how a seat is granted in the first place
- Troubleshooting files and seats — diagnosing seat and access problems
- Plans — Essential vs Spark
- Security architecture — how the gateway and tokens fit the security model