token_revocations
This table stores revocation records used to invalidate active sessions or token-based access immediately, without waiting for natural token expiry.
Purpose
The purpose of this table is to provide immediate access revocation for users, guests, or tenant-scoped sessions when suspension, logout enforcement, or emergency access removal is required.
What this table does
- Stores revocation events that invalidate access
- Supports forced logout and suspension flows
- Allows middleware to reject requests even if a JWT is still technically valid
- Supports immediate revocation for external guest access as well
Why this table is defined
JWTs and sessions often remain valid until expiry. DirtView needs a server-side mechanism to cut off access immediately when a user, tenant, or guest should no longer be allowed in the system.
Columns
| Column | Type | Required | Description | Example |
|---|---|---|---|---|
id | uuid | Yes | Primary key for revocation record | trev_001 |
user_id | uuid | Yes | User whose token/session is revoked | user_123 |
tenant_id | uuid | Yes | Tenant scope of the revocation | tenant_001 |
reason | text | Yes | Why access was revoked | membership_suspended |
revoked_at | timestamptz | Yes | When the revocation took effect | 2026-04-11 15:00:00+00 |
expires_at | timestamptz | No | Optional expiry for temporary revocation logic | NULL |
revoked_by | uuid | No | User/admin who triggered revocation | user_admin_001 |
metadata | jsonb | Yes | Optional revocation details | {"source":"tenant_suspension"} |
Relationships
- tenant_id → tenants.id
- user_id references a platform user
- revoked_by references the actor who enforced revocation
How it is used
- Checked by backend middleware on incoming authenticated requests
- Used when suspending a tenant membership or external access grant
- Used by force-logout workflows in admin systems
- Used to invalidate access without waiting for token expiry
Access and security
- This table is highly security-sensitive
- Writes should be restricted to trusted services and admins
- Checks should happen server-side, never only on the client
- Revocation actions should themselves be audited
Example scenarios
Scenario 1: User suspension
A tenant admin suspends a user, and a revocation record is written immediately.
Scenario 2: External guest revoked
A project manager removes external access before the original expiry date.
Scenario 3: Forced logout
Support forces a logout for troubleshooting or after a security incident.
Notes and assumptions
- This table is operational, not user-facing
- Use indexes on
(tenant_id, user_id, revoked_at desc) - Consider whether tenant-wide revocation needs a separate optimization path