​

JWT Service Authentication

​

Overview

• User Authentication: Better Auth (Session-based) — See Web Authentication
• Service Authentication: JWT + JWKS (Stateless)

​

Authentication Architecture

​

Why Dual-Layer Authentication

User → Web → ai-backend
              ↑
              Anyone can call directly!

User → Web (User Auth) → ai-backend (Service Auth)
                         ↑
                         Only accepts requests from Web

​

How JWT Works

​

Token Acquisition Flow

1. User logs in → Better Auth creates Session
2. Call /api/auth/token → Better Auth issues JWT
3. Web API uses JWT → calls ai-backend
4. ai-backend verifies JWT → validates signature via JWKS

​

Token Structure

eyJhbGciOiJFZERTQSJ9.eyJ1c2VySWQiOiJ1c2VyX2FiYzEyMyJ9.signature
│                    │                                    │
│                    │                                    └─ Signature (EdDSA)
│                    └─ Payload (User Data)
└─ Header (Algorithm Info)

​

JWKS Verification Flow

1. Extract Token: Extract from Authorization: Bearer <token> header
2. Fetch JWKS: Get public key from /api/auth/jwks (with caching)
3. Find Key: Look up corresponding public key using kid from Token Header
4. Verify Signature: Use public key to verify Token has not been tampered with
5. Check Expiration: Verify Token has not expired
6. Return User Info: Extract userId, email, name

​

Protected APIs

​

Require JWT Authentication

​

Do Not Require JWT Authentication

​

Security Best Practices

​

1. Asymmetric Encryption

• Backend does not need shared secrets
• Private key exists only on the Web side
• Supports key rotation

​

2. Key Rotation

• Rotation period: 30 days
• Old keys retained: 30 days

​

3. Token Validity (Dual Token System)

• accessToken is automatically refreshed 5 minutes before expiry
• If refresh fails (refreshToken expired), the user is automatically logged out
• refreshToken is stored as SHA-256 hash in the database

​

Token Refresh Flow

​

Refresh Token Security

• Hash storage: Database stores only SHA-256 hashes; even if leaked, raw tokens cannot be used
• Cascade deletion: All refresh tokens are automatically cleaned up when a user is deleted
• Bulk revocation: All refresh tokens can be revoked by user ID

​

4. JWKS Caching

• Cache duration: 1 hour
• Auto-refreshes during key rotation

​

5. Transport Security

• Production must use HTTPS
• Token is only transmitted in HTTP Header
• Never pass Token in URLs