# Auth and tokens

## Authority (OIDC and OAuth2)
- Issues short-lived OpTok access tokens.
- Tokens are sender-constrained by DPoP or mTLS.
- Audiences and scopes are enforced by each service.

## Token types
- OpTok: short-lived operational access token (minutes).
- Offline token: signed token for air-gap use and local verification.
- PoE: proof of entitlement enforced by Signer.

## Claims (typical)
- iss, sub, aud, exp, iat, nbf, jti, scope
- tid (tenant), inst (installation), roles
- cnf.jkt (DPoP) or cnf.x5t#S256 (mTLS)

## Sender constraints
- DPoP binds the access token to an ephemeral key (cnf.jkt).
- mTLS binds the access token to a client certificate (cnf.x5t#S256).
- High-value audiences should require a DPoP nonce challenge.

## Proof of Entitlement (PoE)
- PoE is enforced by Signer for signing operations.
- OpTok proves who is calling; PoE proves entitlement.
- Enrollment: License Token -> PoE, bound to installation key.

## Recommended flows
- Client credentials for services and automation.
- Device code for CLI interactive login.
- Authorization code with PKCE for UI logins.

## Validation rules (resource servers)
- Verify signature, issuer, audience, exp, nbf, and scope.
- Enforce sender constraints (DPoP or mTLS).
- Enforce tenant and installation boundaries.

## Key rotation
- JWKS exposes active and retired keys.
- Keep old keys for the max token lifetime plus skew.

## Introspection
- Optional for services that require online token validation.