Auth Token Shape

May contain stale references

This document was audited on 2026-06-22 and contains references that need updating: OAuth JWTs signed by webapp; service tokens use separate issuer. Cross-check critical details against the current codebase before relying on them.

Overview

This document describes the JWT bearer‑token format used across the ERP‑Unlocked monorepo for service‑to‑service authentication.

Current Claim Set

All internal bearer tokens are JWTs signed by Clerk (or the internal token issuer for background services). The payload includes the following standard and custom claims:

• sub – Subject identifier (user or service ID).
• iss – Issuer (https://clerk.com for Clerk tokens, or internal for ops‑mcp).
• exp – Expiration time (seconds since epoch).
• iat – Issued‑at timestamp.
• org_id – Organization identifier (present in Clerk Session JWT V2).
• org_role – Role within the organization (e.g., admin, member).
• scopes – Optional array of scopes granted to the token. This claim is present in apps/graph-mcp and apps/webapp tokens. If a token lacks the scopes claim, services MUST treat it as an explicit empty set (no scopes granted) and restrict the request to endpoints that do not perform fine‑grained permission checks. This least‑privilege default applies uniformly across apps/graph-mcp, apps/webapp, and any future service that consumes these tokens.

Note: The presence of the scopes claim was confirmed in apps/graph-mcp. If future services (e.g., apps/ops-mcp) need finer‑grained access, they can include this claim. Adding it will add ~2 days of work in Sprint 1.

Usage

When a request arrives with an Authorization: Bearer <token> header, the following steps occur:

1. Verify the JWT signature using the public key configured for the issuer.
2. Validate exp and iat timestamps.
3. Extract the sub, org_id, and scopes (if present).
4. Authorisation middleware checks the required scope for the endpoint against the token’s scopes array. If the claim is missing, the request is treated as having an empty set of scopes (no permissions granted) and is allowed only for endpoints that do not perform fine‑grained permission checks.

References

• apps/webapp/src/lib/api/validate-internal-token.ts – token validation implementation.
• apps/graph-mcp/src/worker.ts – example of a service that expects the scopes claim.