docs: clarify JWT claims requirements - only sub is required

[devin-ai-integration]

Description

Updated the JWT claims documentation in the security and authentication page to clarify the actual requirements for JWT tokens used with Knock's enhanced security mode.

What changed:

• Modified the JWT claims section to clarify that only sub is required
• Updated iat and exp claims from "required" to "recommended for security"
• Added inline comments in the JSON example to distinguish required vs recommended claims

Why this change:
The previous documentation incorrectly stated that all three claims (sub, iat, exp) were required at minimum, when in reality only the sub claim is actually validated as required by the backend. This was causing confusion for developers implementing JWT authentication.

How it was changed:

• Changed descriptive text from "At a minimum, the JWT to be signed must contain:" to "The JWT must contain the sub claim, and should include iat and exp claims for security:"
• Updated JSON comments to indicate (required) for sub and (recommended) for iat/exp

Tasks

Addresses feedback from Slack #eng-ai-tasks channel requesting clarification of JWT claims requirements.

Human Review Checklist

• Verify technical accuracy: Confirm that only sub is actually required by checking backend validation logic
• Check documentation consistency: Search for other JWT-related documentation that might need similar updates
• Validate clarity: Ensure the new wording clearly communicates the distinction between required and recommended claims
• Consider impact: Assess whether existing developer implementations might be affected by this clarification

Note: This change was requested by Scoti Dodson ([email protected]) and implemented by Devin AI in session: https://app.devin.ai/sessions/e16f85da74a34fc6b552e7f55febc50c

Risk Assessment

The main risk is ensuring technical accuracy - this change is based on user feedback rather than direct verification of backend validation code. The change is documentation-only and improves clarity, but reviewers should verify it accurately reflects actual API behavior.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Aug 22, 2025 4:00pm

[scoti-knock]

Suggested change

	Your JWT will need to be signed against your **private signing key** using an **RS256** algorithm. The JWT must contain the `sub` claim, and should include `iat` and `exp` claims for security:
	Your JWT will need to be signed against your **private signing key** using an **RS256** algorithm. The JWT must contain the `sub` claim and we recommend also including `iat` and `exp` to enforce token expiration.