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), orjjwt(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, andscopesin the payload. - Create authentication middleware that extracts the Bearer token from the
Authorizationheader, 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.rolesagainst 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-Keyheader. - 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
- RFC 7519 JSON Web Token (JWT): https://tools.ietf.org/html/rfc7519
- RFC 6749 OAuth 2.0 Authorization Framework
- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/
- Auth0 architecture patterns: https://auth0.com/docs/