AGENTS.md Template: JWT Security Architecture

Overview

AGENTS.md template for JWT security architecture provides a complete operating manual for single-agent and multi-agent orchestration of token-based security. It defines roles, rules, and collaboration patterns that enable AI coding agents to design, implement, validate, and operate a JWT-based security stack with auditable handoffs and governance. Directly actionable and copyable, this page ensures teams have a concrete AGENTS.md Template to anchor JWT policy, key management, and token workflows.

Direct answer: This template codifies roles, handoffs, and guardrails needed to govern JWT-based security across an AI-driven workflow.

When to Use This AGENTS.md Template

• Designing a token-based authentication and authorization flow for microservices and APIs.
• Coordinating single-agent or multi-agent security workflows that include token issuance, validation, and key rotation.
• Providing a reproducible operating context for governance, audits, and human review in JWT deployments.
• Establishing a clear handoff protocol between planner, implementer, reviewer, tester, and domain experts.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: JWT Security Architecture Lead

Agent roster and responsibilities:
- Architect (Planner): defines JWT policy: issuer, audience, expiration, rotation, revocation; ensures compliance with OWASP standards and auditability.
- TokenIssuer: issues access and refresh tokens; retrieves signing keys from KeyManager; enforces token scopes.
- KeyManager: handles key generation, rotation, JWKS publication, and revocation of compromised keys.
- TokenValidator: validates incoming tokens against issuer, audience, and signature; checks clock skew and claims.
- RevocationResponder: processes revocation requests and propagates revocation to downstream services.
- Auditor: monitors token workflows, access patterns, and anomaly detection; maintains an immutable audit log.
- Integrator: connects the JWT stack to identity providers, IAM, and API gateways.

Supervisor or orchestrator behavior:
- Central Orchestrator coordinates policy changes, token lifecycle events, and handoffs; enforces time-based escalation and logging.
- All artifacts and decisions are versioned and stored in a central repository; changes require peer review and security sign-off.

Handoff rules between agents:
- Policy change or key rotation triggers a Planner-to-Implementer handoff with a mapped artifacts list (policy.md, JWKS, token templates).
- Implementer delivers artifacts to Reviewer; upon approval, to Auditor and Orchestrator for deployment.
- Handoffs are logged in the audit log with timestamps and agent IDs.

Context, memory, and source-of-truth rules:
- Use a single policy document: /auth/jwt/policy.md as the source of truth.
- All runtime decisions reference the policy and validated configurations stored in a versioned store.
- Token metadata and telemetry are written to a tamper-evident log.

Tool access and permission rules:
- Agents have read access to policy and identity docs; write access restricted to designated directories.
- Secrets must reside in a secrets vault; rotation is automated on schedule or on incident.
- External calls to identity providers or auth services require approved scopes and audit trails.

Architecture rules:
- Stateless tokens using RS256 with JWKS-based verification.
- Centralized authorization gateway enforces issuer, audience, and scope checks.
- Key rotation must be validated and propagated without service downtime.

File structure rules:
- /auth/jwt/policy.md
- /auth/jwt/keys/
- /auth/jwt/logs/
- /auth/jwt/services/
- /auth/jwt/tests/

Data, API, or integration rules when relevant:
- Validate tokens against issuer, audience, and configured claims.
- Use JWKS for public key retrieval with caching and refresh.
- Respect CORS and API gateway policies when exposing token info.

Validation rules:
- Signature verification, audience/issuer checks, and allowed clock skew.
- Token expiry and revocation status must fail closed.
- All changes must pass peer review and automated tests.

Security rules:
- TLS everywhere; least privilege for all services; secrets rotated and audited.
- Monitor for key compromise and automated revocation.
- Do not bypass token verification or expose signing keys.

Testing rules:
- Unit tests for token generation, signing, and validation.
- Integration tests across issuer, validator, and gateway integrations.
- End-to-end tests including rotation and revocation.

Deployment rules:
- Feature flags for rotation events; canary deployments for major policy changes.
- Rollback to previous key/version if validation fails post-deploy.

Human review and escalation rules:
- Any security policy change or key rotation requires Security Lead sign-off.
- On suspected compromise, escalate immediately to incident response and halt token issuance.

Failure handling and rollback rules:
- If rotation or issuer validation fails, revert to previous stable keys and pause issuance.
- Roll back deployments and invalidate new tokens until issue is resolved.

Things Agents must not do:
- Do not issue tokens for unauthenticated clients; do not bypass revocation checks.
- Do not store secrets in plaintext; do not bypass TLS or network controls.
- Do not perform production changes without approval or bypassing audit requirements.

Recommended Agent Operating Model

The JWT Security Architecture operates with a defined roster and clear decision boundaries. The Planner designs the policy and roadmaps, the Implementer encodes and deploys the policy into the token issuance flow, the Reviewer validates correctness and security posture, the Tester verifies end-to-end behavior, the Researcher analyzes evolving threat models, and the Domain Specialist ensures alignment with specific identity providers and regulatory requirements. Escalation paths route incidents to the Orchestrator and Security Lead.

Recommended Project Structure

jwt-security-architecture/
├─ auth/
│  ├─ jwt/
│  │  ├─ policy.md
│  │  ├─ keys/
│  │  ├─ logs/
│  │  ├─ services/
│  │  └─ tests/
│  └─ docs/
├─ agents/
│  ├─ planner/
│  ├─ implementer/
│  ├─ reviewer/
│  ├─ tester/
│  ├─ researcher/
│  └─ domain-specialist/
├─ integrations/
│  ├─ identity-providers/
│  └─ api-gateways/
└─ scripts/

Core Operating Principles

• Single source of truth for JWT policy and key management.
• Explicit, auditable handoffs between agents with time-stamped logs.
• Least privilege and secret management by design.
• Idempotent actions and deterministic outputs for all workflows.
• Clear escalation paths for security incidents and policy changes.
• Continuous improvement through automated checks and post-incident reviews.

Agent Handoff and Collaboration Rules

• Planner ↔ Implementer: deliver policy, token templates, and JWKS configuration artifacts.
• Implementer ↔ Reviewer: deliver code, configuration, and test results; include rationale notes.
• Reviewer ↔ Tester: approve test plans and results; ensure coverage of token validation, rotation, and revocation.
• Researcher ↔ Domain Specialist: incorporate provider-specific claims, scopes, and metadata.
• Domain Specialist ↔ Orchestrator: confirm alignment with governance and regulatory requirements.

Tool Governance and Permission Rules

• Commands and scripts must run in a controlled environment with traceability.
• Edits to policy and keys require peer review and security sign-off.
• Secrets must be retrieved from a vault; never hard-coded.
• Production changes require approvals, tests, and canary validation.
• External calls must use authenticated endpoints with least privilege scopes.

Code Construction Rules

• Code must be deterministic and reproducible; include versioning and tests.
• Token generation and validation modules must be modular and well-typed.
• Follow established JWT best practices: RS256, aud/iss validation, and claim checks.
• Document all policy decisions in policy.md with traceable references.

Security and Production Rules

• TLS everywhere and mutual TLS where applicable; rotate keys before compromise window.
• Audit logging enabled; tamper-evident storage for logs.
• Never bypass revocation checks; monitor for anomalies in token usage.
• Impact assessments required for policy changes; rollback plans in place.

Testing Checklist

• Unit tests for token signing/verification
• Integration tests with identity providers
• End-to-end tests for rotation and revocation
• Security tests: tamper detection, replay protection
• Deployment tests: canary and rollback procedures

Common Mistakes to Avoid

• Skipping revocation checks or improper key rotation timing
• Hard-coding secrets or exposing signing keys
• Unclear policy decisions or missing audit traces
• Overlooking clock skew or incorrect audience checks
• Inadequate coverage in test plans

FAQ

What is the purpose of this AGENTS.md Template?

It provides a copyable, policy-driven operating manual for JWT security architecture that supports both single-agent and multi-agent orchestration.

Which agent roles are defined for JWT security architecture?

Architect (Planner), TokenIssuer, KeyManager, TokenValidator, RevocationResponder, Auditor, Integrator, with a centralized Orchestrator coordinating activities.

How does handoff work between planners, implementers, and reviewers?

Handoffs are time-stamped, versioned artifacts exchanged through a central repository; each transfer requires sign-off and audit logging.

How are secrets and JWKS handled securely?

Secrets reside in a vault with strict access controls, rotation, and audit trails; JWKS are fetched securely with caching and rotation intact.

What happens on failure or rotation?

On failure, revert to prior stable keys, pause issuance, and redeploy with validated changes; rotate keys only after successful validation and canary checks.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Gym Franchises Using Excel To Analyze Membership Peak Check-In Times and Adjust Staffing Levels.