Skip to content
Skills Library
Security · Building & coding

jwt

/jwt

Expert JSON Web Token (JWT) assistance covering RS256/HS256 signing, claims validation, expiration, and refresh token rotation. Use when securing APIs, signing auth tokens, or debugging invalid signature errors.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
10
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert JSON Web Token (JWT) assistance covering RS256/HS256 signing, claims validation, expiration, and refresh token rotation. Use when securing APIs, signing auth tokens, or debugging invalid signature errors.

Original author description

Expert JSON Web Token (JWT) assistance covering RS256/HS256 signing, claims validation, expiration, and refresh token rotation. Use when securing APIs, signing auth tokens, or debugging invalid signature errors.

How it works

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Original SKILL.md headings · 163 lines, 652 words
SKILL.md preview
---
name: jwt
description: Expert JSON Web Token (JWT) assistance covering RS256/HS256 signing, claims validation, expiration, and refresh token rotation. Use when securing APIs, signing auth tokens, or debugging invalid signature errors.
---

# JSON Web Token (JWT)

JWT is a compact, URL-safe means of representing claims to be transferred between two parties. The claims are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) or JSON Web Encryption (JWE).

## When to Use

- **Stateless Authorization Tokens**: Transmitting verified user identity and permission claims between microservices without database session lookups.
- **OAuth 2.0 / OpenID Connect Bearer Tokens**: Serving signed access and ID tokens across distributed web and mobile applications.
- **Short-Lived Temporary Access Grants**: Generating signed, time-limited tokens for password resets, email verification, or file downloads.
- **Decoupled Microservice Verification**: Allowing independent microservices to verify token signatures locally using shared public keys (JWKS).

## Quick Start

`Header.Payload.Signature`

```json
// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload (Claims)
{
  "sub": "1234567890", // Subject (User ID)
  "name": "John Doe",
  "iat": 1516239022,    // Issued At
  "exp": 1516242622,    // Expiration
  "role": "admin"
}

// Signature
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)
```

## Core Concepts

### JWT Structure (Header.Payload.Signature)

A compact, URL-safe base64url-encoded string consisting of three cryptographic segments:

```text
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNzI3NDIwNDAwfQ.XwG...
───────────────────────────────────── ────────────────────────────────────────────────────────────────────────── ───────
                │                                                         │                                         │
             Header                                                    Payload                                  Signature
   (Algorithm & Token Type)                                       (Registered & Custom Claims)              (Cryptographic Proof)
```

### Asymmetric RS256 Signing (Private Key Signs, Public Key Verifies)

Authentication servers sign tokens with a private key; downstream microservices verify with the public key:

```typescript
import jwt from "jsonwebtoken";
import fs from "fs";

const privateKey = fs.readFileSync("private.key");
const publicKey = fs.readFileSync("public.key");

// Sign token (Auth Server)
const token = jwt.sign(
  { sub: "usr_415", role: "admin", orgId: "org_99" },
  privateKey,
  {
    algorithm: "RS256",
    expiresIn: "15m",
    issuer: "https://auth.example.com",
    audience: "https://api.example.com",
  },
);

// Verify token (Resource Server / API)
const claims = jwt.verify(token, publicKey, {
  algorithms: ["RS256"],
  issuer: "https://auth.example.com",
  audience: "https://api.example.com",
});
```

### JSON Web Key Sets (JWKS) Automated Key Rotation

Resource servers dynamically fetch verified public keys without hardcoding static files:

```typescript
import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://auth.example.com/.well-known/jwks.json"),
);

const { payload } = await jwtVerify(token, JWKS, {
  issuer: "https://auth.example.com",
  audience: "https://api.example.com",
});
```

## Common Patterns

### Asymmetric Token Verification with Key Rotation (JWKS)

**Problem**: Hardcoding symmetric HMAC secrets creates key leakage risks across microservices.

**Solution**:
Use RS256 asymmetric signing with `jwks-rsa` public key retrieval:

```javascript
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const client = jwksClient({
  jwksUri: "https://auth.example.com/.well-known/jwks.json",
  cache: true,
  rateLimit: true,
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    callback(null, key ? key.getPublicKey() : null);
  });
}

export function verifyToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, { algorithms: ["RS256"] }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}
```

## Best Practices

**Do**:

- Keep Access Token Expiration Brief (5-15 Minutes): Pair short-lived access tokens with secure refresh token rotation to minimize leakage windows.
- Always Validate `iss`, `aud`, and `exp` Claims: Never verify signature alone; ensure the token is targeted for your API and not expired.
- Use Asymmetric RS256 or EdDSA Algorithms: Never use symmetric HS256 for multi-service architectures where sharing secrets is a liability.
- Explicitly Whitelist Expected Algorithms: Enforce `algorithms: ['RS256']` in verification options to prevent algorithm confusion attacks (`none` or HS256).

**Don't**:

- Put sensitive PII or secrets in the payload: JWT payloads are merely base64 encoded and can be read by anyone with access to the token.
- Store JWTs in browser localStorage: Store auth tokens in HttpOnly, Secure, SameSite cookies to protect against XSS token theft.
- Create unbounded token sizes: Keep claims minimal; large tokens bloat every HTTP header and degrade network latency.

## Troubleshooting

| Error               | Cause                            | Solution                                     |
| :------------------ | :------------------------------- | :------------------------------------------- |
| `TokenExpiredError` | `exp` time passed.               | Refresh the token using a Refresh Token.     |
| `JsonWebTokenError` | Malformed or Signature mismatch. | Check secret/public key and token integrity. |

## References

- [jwt.io](https://jwt.io/)
- [RFC 7519](https://tools.ietf.org/html/rfc7519)

Versions

RepositoryScoreLicence
This page · G1Joshi/Agent-Skills100MIT
claude-dev-suite/claude-dev-suite100MIT
kataras/jwt95MIT

Database snapshot: 13.11.2026 · package version a4488f6cff80 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100jwt-handler
    When the user needs to generate, validate, refresh, or debug JSON Web Tokens. Use when the user mentions "JWT," "access token," "refresh token," "token rotation," "token expiration," "token validation," "bearer token," or "decode JWT." Handles secure token lifecycle including…
  • 100session-management-stateless-jwt
    Use this skill when implementing secure authentication tokens, refresh token rotation, and stateless JWT validation.
  • 100jwt-security-signature-verification-claims
    Use this skill when validate JSON Web Tokens verifying cryptographic signatures, issuer, audience, and expiration claims.
  • 100jwt-session-management-hardening
    Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session…
  • 90implementing-jwt-signing-and-verification
    Implements secure JWT (RFC 7519) signing and verification using HMAC-SHA256, RSA-PSS, ES256, and EdDSA, including token expiration, claims validation, and defenses against algorithm-confusion, none-algorithm, and key-injection attacks. Use when adding or hardening JWT-based…
  • 100jwt-token-validator
    Validate jwt token validator operations. Auto-activating skill for Security Fundamentals. Triggers on: jwt token validator, jwt token validator Part of the Security Fundamentals skill category. Use when working with jwt token validator functionality. Trigger with phrases like…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.