Revocation Checking

JWTs issued by the have expiry times, but a user can also revoke a before its expiry. When a mandate is revoked, all JWTs issued against it are invalidated immediately — not just at their next expiry. Sumvin enforces this on its own endpoints: every API request that presents a Stamped Mandate JWT is checked against the mandate’s live status. Once the mandate is revoked, the very next request presenting one of its tokens is refused with 401 Unauthorized and error code PINT-401-006 — there is no propagation delay. As a verifier running your own gate, you should also check revocation status so you can reject withdrawn credentials before you act on them, rather than relying solely on the calls you make to Sumvin. A Stamped Mandate is delivered over the API as a PINT (header x-sumvin-pint-token), so the status endpoint, the pint_uri claim, and the PINT-4xx error codes below all use the PINT identifier on the wire.

Endpoint

GET /v0/sis/pint/{pint_id}/status

Authentication: API key via Authorization: Bearer header. This endpoint is deliberately permissive — any authenticated third-party caller with a valid SIS API key can check the status of any Stamped Mandate they’ve been presented with. No specific scope is required.

Request

Extract the mandate’s identifier from the JWT’s pint_uri claim and call the status endpoint:

curl "https://sis.sumvin.com/v0/sis/pint/sr%3Aus%3Apint%3Aabc123/status" \
  -H "Authorization: Bearer <your-api-key>"

The SRI contains colons that must be URL-encoded as %3A in the path. Most HTTP libraries handle this automatically with encodeURIComponent() or urllib.parse.quote().

Response — Valid

{
  "id": "sr:us:pint:abc123",
  "valid": true,
  "reason": null,
  "revoked_at": null,
  "_links": {
    "self": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123/status" },
    "pint": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123" }
  }
}

Response — Revoked

{
  "id": "sr:us:pint:abc123",
  "valid": false,
  "reason": "revoked",
  "revoked_at": 1739443800000,
  "_links": {
    "self": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123/status" },
    "pint": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123" }
  }
}

Response — Expired

{
  "id": "sr:us:pint:abc123",
  "valid": false,
  "reason": "expired",
  "revoked_at": null,
  "_links": {
    "self": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123/status" },
    "pint": { "href": "/v0/sis/pint/sr%3Aus%3Apint%3Aabc123" }
  }
}

Field	Type	Description
`id`	string	The Stamped Mandate’s SRI
`valid`	boolean	`true` if the mandate is active and not expired; `false` if revoked or expired
`reason`	string or null	`null` when valid; `"revoked"` or `"expired"` when invalid
`revoked_at`	integer (epoch milliseconds) or null	Timestamp of when the mandate was revoked. `null` when the mandate is valid or has only expired without explicit revocation
`_links.self`	object	Link back to this status endpoint
`_links.pint`	object	Link to the full Stamped Mandate resource

Timestamps default to epoch milliseconds. To receive ISO 8601 strings instead (e.g., "2026-02-13T11:30:00Z"), send the header X-Timestamp-Format: iso8601. This applies to revoked_at and any other _at fields in the response.

Error Responses

Status	Error Code	Description
`401`	—	Missing or invalid API key.
`404`	`PINT-404-001`	No Stamped Mandate exists for the given SRI. Response follows RFC 7807; see `detail` for the decoded SRI that failed lookup.

Implementation Examples

TypeScript

interface RevocationStatus {
  id: string;
  valid: boolean;
  reason: "revoked" | "expired" | null;
  revoked_at: number | null;
}

async function checkRevocation(pintUri: string): Promise<boolean> {
  const response = await fetch(
    `https://sis.sumvin.com/v0/sis/pint/${encodeURIComponent(pintUri)}/status`,
    { headers: { Authorization: `Bearer ${process.env.SIS_API_KEY}` } }
  );

  if (!response.ok) {
    throw new Error(`Revocation check failed: ${response.status}`);
  }

  const status: RevocationStatus = await response.json();
  return status.valid;
}

// Usage in your request handler
const pintUri = jwtPayload.pint_uri as string;
const isValid = await checkRevocation(pintUri);
if (!isValid) {
  return new Response("PINT has been revoked", { status: 403 });
}

Python

import requests
from urllib.parse import quote

def check_revocation(pint_uri: str, api_key: str) -> bool:
    response = requests.get(
        f"https://sis.sumvin.com/v0/sis/pint/{quote(pint_uri, safe='')}/status",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    response.raise_for_status()

    status = response.json()
    return status["valid"]

# Usage
pint_uri = jwt_payload["pint_uri"]
if not check_revocation(pint_uri, SIS_API_KEY):
    raise PermissionError("PINT has been revoked")

Caching Guidance

The revocation check endpoint is designed for low latency (< 100ms p99) and responses are already cached server-side for 30 seconds. You should still cache on your side to avoid excessive calls: Recommended approach: Cache the valid: true response for 30 seconds. This matches the server-side cache TTL and balances freshness (revocations propagate within 30s) with throughput. Do not cache indefinitely. A Stamped Mandate that was valid at verification time may be revoked seconds later. The 30-second TTL provides a reasonable window. Cache valid: false longer. Once a Stamped Mandate is revoked or expired, it doesn’t come back. You can cache negative results for the duration of the JWT’s remaining lifetime.

import { LRUCache } from "lru-cache";

const revocationCache = new LRUCache<string, boolean>({
  max: 10000,
  ttl: 30 * 1000, // 30 seconds for valid results
});

async function checkRevocationCached(pintUri: string): Promise<boolean> {
  const cached = revocationCache.get(pintUri);
  if (cached !== undefined) return cached;

  const isValid = await checkRevocation(pintUri);
  revocationCache.set(pintUri, isValid, {
    ttl: isValid ? 30 * 1000 : 300 * 1000, // 30s for valid, 5min for revoked
  });
  return isValid;
}

When to Check

Always check on the first request for a given Stamped Mandate in a session. After that, your cache handles subsequent checks within the TTL. Skip the check if you don’t have an SIS API key. JWT signature verification and expiry checking are still valid without revocation checking — you just won’t catch mandates that were revoked before their natural expiry.

Sigil — Identity & Mandates

Verifier Guide

API Reference

Endpoint

Request

Response — Valid

Response — Revoked

Response — Expired

Error Responses

Implementation Examples

TypeScript

Python

Caching Guidance

When to Check

​Endpoint

​Request

​Response — Valid

​Response — Revoked

​Response — Expired

​Error Responses

​Implementation Examples

​TypeScript

​Python

​Caching Guidance

​When to Check

Endpoint

Request

Response — Valid

Response — Revoked

Response — Expired

Error Responses

Implementation Examples

TypeScript

Python

Caching Guidance

When to Check