JWT Access and Refresh Tokens

The production problem this solves

Good work on JWT Access and Refresh Tokens leaves evidence: a visible behavior, a stable contract or a repeatable operational check. This lesson defines an application trust boundary, where an explicit contract is safer than framework convention or an undocumented assumption.

Here, that decision supports a specific checkpoint: Threat-model a mobile CourseFlow client and a third-party calendar integration, then select the correct authorization flow for each. A reviewable result should include a repeatable request, automated test, query result and failure response rather than a claim that the feature simply works.

A practical model for jwt access and refresh tokens

Use short-lived signed access tokens only where their portability is worth revocation and storage complexity. The useful unit of understanding is the boundary: who owns the decision, which input crosses it, what result is visible and how a failure is reported.

• Claims: Compare the simplest correct approach with one credible alternative.
• Signature Verification: State the assumption this concept relies on and show how the system behaves when it is false.
• Access Lifetime: Connect this concept to the module checkpoint and identify the evidence a reviewer should expect.
• Refresh Rotation: Explain the concept without framework jargon, then point to it in the working example.

Engineering decisions for JWT Access and Refresh Tokens

These are the details that separate a working demonstration from a maintainable production decision.

• Do not accept algorithms from untrusted token input without a strict verification policy.
• Keep access tokens short-lived and design refresh rotation, revocation and replay handling before production.
• Never place secrets or unnecessary personal data in a JWT: signing prevents alteration, not disclosure.

Explain each moving part

The sample is intentionally narrow. Its job is to expose claims without hiding the decision behind unrelated setup.

import { jwtVerify } from 'jose';

const issuer = 'https://identity.example.test';
const audience = 'courseflow-api';

export async function verifyAccessToken(token: string, key: CryptoKey) {
  const { payload } = await jwtVerify(token, key, { issuer, audience });
  if (typeof payload.sub !== 'string') throw new Error('missing subject');
  return payload;
}

Trace the implementation boundary

1. 1
   Claims

   Keep names tied to the product rule so a reviewer can follow the change without decoding abbreviations.

2. 2
   Signature Verification

   Add a regression check close to the boundary where this behavior can fail.

3. 3
   Access Lifetime

   Describe the behavior in one sentence, then choose the smallest input that can prove it.

4. 4
   Refresh Rotation

   Add this responsibility at the narrowest sensible boundary; do not pull an unrelated layer into the change.

Check your reasoning

What to carry into the next lesson

• Use short-lived signed access tokens only where their portability is worth revocation and storage complexity.
• Keep claims visible at the boundary where it can be tested.
• Use evidence from signature verification before widening the implementation.

References and related reading

• JWT best current practices (RFC 8725)