OAuth 2.1 + OIDC

NamoID is an OAuth 2.1 + OIDC Core 1.0 authorization server. Every project environment exposes a full discovery document at <issuer>/.well-known/openid-configuration, so any standards-compliant client integrates without bespoke glue.

What "OAuth 2.1" means here

OAuth 2.1 consolidates the security best practices that accumulated since OAuth 2.0. NamoID follows it strictly:

• PKCE is required on every flow. Even confidential clients must send a code challenge — and only S256 is advertised, never plain. This defends against authorization-code interception at the cost of nothing real.
• Authorization code is the only response type. response_types_supported is ["code"]. There is no implicit flow.
• No password grant. Long deprecated; not accepted. grant_types_supported is ["authorization_code", "refresh_token"].
• Refresh tokens rotate. Every grant_type=refresh_token exchange issues a new refresh token and revokes the old one. Replaying an old refresh token triggers a chain-revoke — every descendant refresh is invalidated and a security.refresh_replay event is written to the audit log.

Confidential clients authenticate at the token endpoint with client_secret_basic or client_secret_post.

What "OIDC" adds

OpenID Connect layers identity onto OAuth. NamoID's ID tokens are RS256-signed JWTs whose public keys are published at the issuer's discovered jwks_uri. Keys are rotated on a regular cadence with overlapping validity windows, so tokens signed by the previous key keep verifying until they expire — verifiers never hit a hard cutover. Clients should always fetch keys from the JWKS endpoint by kid rather than pinning a key.

Identity claims available in tokens include name, email, email_verified, phone_number, and phone_number_verified, alongside the standard protocol claims (sub, iss, aud, exp, iat, auth_time, nonce). See Tokens & claims for the full list and validation guidance.

Supported scopes

Scope	Grants
openid	Required for OIDC; produces an ID token
profile	name and profile claims
email	email, email_verified
phone	phone_number, phone_number_verified
offline_access	A refresh token for long-lived sessions

Token lifetimes

Token	Lifetime	Notes
Authorization code	10 minutes	Single use; bound to the PKCE verifier
Access token	15 minutes	RS256 JWT
ID token	15 minutes	Issued alongside the access token
Refresh token	30 days	Rotates on every use

Clock skew of ±30 seconds is tolerated when validating token timestamps.

Endpoints

All endpoints are discovered from the issuer; you should never hardcode them. For the exact paths, parameters, and the full discovery document, see the OIDC endpoints reference.