app/stories/developer/DEV-007-jwt-validation.md

Validate JWTs in My Application

ID: DEV-007 Priority: Medium Status: Planned

User Story

As a developer, I want clear guidance and tools to validate JWTs issued by the identity provider so that I can securely authenticate users in my backend services.

Acceptance Criteria

• Public key endpoint for JWT validation (JWKS format)
• Documentation explaining JWT structure and claims
• Example code for validation in multiple languages
• Key rotation with multiple valid keys during transition
• Token introspection endpoint for server-side validation
• Clear error messages for invalid tokens
• Guidance on caching public keys

Technical Notes

• getPublicKeyForValidation endpoint exists
• Consider standard JWKS endpoint (/.well-known/jwks.json)
• OpenID Connect discovery endpoint would help
• JWTs contain: sub, email, roles, orgId, exp, iat
• Document all custom claims in JWT

Related TODOs

• Enhancement to existing JWT infrastructure