Access Tokens — Proposed Guide

Access Tokens: An access token would carry or reference a short-lived authorization context for a particular audience. Possession of the token must not…

Overview

An access token would carry or reference a short-lived authorization context for a particular audience. Possession of the token must not remove resource-level organization checks.

Key concepts

Validate the audience, expiry and allowed scopes. An opaque token requires a server-side lookup; a signed token requires trusted signature and claim validation.

Implementation considerations

Never decode a token and assume that decoding verifies it. Token formats and lifetimes are undecided for the proposed API.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

{
  "reference_only": true,
  "topic": "Access Tokens",
  "audience": "example-api-audience",
  "scope": [
    "expenses:read"
  ],
  "expires_at": "2026-01-15T12:00:00Z",
  "principal_id": "principal_example_123"
}

Design review checklist

• Document which organization owns the access tokens representation and which actor may view or change it.
• Test the boundaries of audience, scope, expires at, principal id using synthetic values, including missing or inconsistent references.
• Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Related documentation