Building API Authentication
Overview
Build secure API authentication systems supporting JWT Bearer tokens, OAuth 2.0 authorization code and client credentials flows, API key management, and session-based authentication. Implement token issuance, validation, refresh rotation, revocation, and role-based access control (RBAC) with scoped permissions across all API endpoints.
Prerequisites
- Cryptographic library:
jsonwebtoken (Node.js), PyJWT (Python), or jjwt (Java)
- Secure secret storage: environment variables, AWS Secrets Manager, or HashiCorp Vault for JWT signing keys
- Database table for user credentials, refresh tokens, and API key storage
- Bcrypt or Argon2 for password hashing (never store plaintext passwords)
- OAuth 2.0 provider credentials for third-party auth integration (Google, GitHub, Auth0)
Instructions
- Examine existing authentication setup using Grep and Read, identifying current auth mechanisms, middleware placement, and any endpoints bypassing authentication.
- Implement JWT token issuance on successful login: sign with RS256 (asymmetric) or HS256 (symmetric), including
sub (user ID), iat, exp (15-minute access token), roles, and scopes in the payload.
- Create authentication middleware that extracts the Bearer token from the
Authorization header, verifies the signature and expiration, and injects the decoded user context into the request object.
- Implement refresh token rotation: issue a long-lived refresh token (30 days) alongside the access token, store a hash of the refresh token in the database, and rotate on each refresh (invalidating the previous token).
- Build role-based access control (RBAC) middleware that checks
user.roles against endpoint-required roles, supporting both role-level (admin, user) and scope-level (read:users, write:orders) authorization.
- Add API key authentication as an alternative to JWT for machine-to-machine communication: generate cryptographically random keys, store hashed values, and validate against the
X-API-Key header.
- Implement OAuth 2.0 client credentials flow for service-to-service authentication, with token caching and automatic renewal before expiration.
- Add brute-force protection on login endpoints: rate limit to 5 attempts per minute per IP, implement progressive lockout (15 min, 1 hour) after repeated failures, and log all authentication attempts.
- Write security tests covering: valid/invalid/expired tokens, refresh token rotation, role enforcement, API key validation, brute-force lockout, and token revocation.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/src/auth/jwt.js - JWT token issuance, verification, and refresh logic${CLAUDE_SKILL_DIR}/src/auth/middleware.js - Bearer token authentication middleware${CLAUDE_SKILL_DIR}/src/auth/rbac.js - Role-based and scope-based access control middleware${CLAUDE_SKILL_DIR}/src/auth/api-keys.js - API key generation, hashing, and validation${CLAUDE_SKILL_DIR}/src/auth/oauth.js - OAuth 2.0 flow implementations${CLAUDE_SKILL_DIR}/src/routes/auth.js - Login, register, refresh, and logout endpoints${CLAUDE_SKILL_DIR}/tests/auth/ - Authentication and authorization security tests
Error Handling
| Error | Cause | Solution |
|---|
| 401 Token Expired | JWT exp claim is in the past | Client should attempt token refresh; if refresh fails, redirect to login |
| 401 Invalid Signature | JWT signed with different key or tampered payload | Verify signing key matches between issuance and validation; check for key rotation issues |
| 403 Insufficient Scope | Authenticated user lacks required role/scope for endpoint | Return required scope in error body; log authorization failure with user and endpoint details |
| Refresh token reuse | Previously rotated refresh token used (possible token theft) | Invalidate all user sessions immediately; alert user of potential compromise; require re-authentication |
| API key leaked | API key exposed in client-side code, logs, or version control | Revoke compromised key immediately; issue replacement; scan for exposure source |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
JWT with refresh rotation: Login returns {accessToken (15min), refreshToken (30d)}; client stores refresh token securely; on 401, client calls POST /auth/refresh with old refresh token, receives new pair, old refresh token is invalidated.
Multi-provider OAuth: Support "Sign in with Google" and "Sign in with GitHub" using OAuth 2.0 authorization code flow, creating local user accounts on first sign-in and linking subsequent provider connections.
API key with scoped permissions: Generate API keys with specific scopes (read:analytics, write:webhooks), stored as SHA-256 hashes, displayed to the user only once at creation, with key rotation support.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
