playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / backend-api-authentication

backend-api-authentication skill

/.claude/skills/backend-api-authentication

This skill helps you implement secure API authentication in TypeScript by guiding token handling, OAuth2 flows, and password security across endpoints.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill backend-api-authentication

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: Backend API Authentication
description: Implement secure API authentication following industry best practices including token-based auth, OAuth2/OIDC, JWT handling, and password security. Use this skill when implementing or modifying authentication mechanisms, login endpoints, token generation or validation logic, user session management, password hashing or verification, API security middleware, authentication guards or decorators, OAuth2 flows, API key management, or any backend code that handles user credentials, access tokens, refresh tokens, or API authentication. Use when creating new auth endpoints, updating existing authentication logic, reviewing security vulnerabilities in auth code, implementing rate limiting for login endpoints, or working with authentication-related database models and queries.
---

## When to use this skill

- When implementing or modifying authentication endpoints (login, logout, token refresh)
- When writing or updating token generation, validation, or verification logic
- When creating or modifying password hashing, verification, or reset functionality
- When implementing OAuth2, OIDC, or other authentication flows
- When working with authentication middleware, guards, or decorators
- When creating or updating user session management code
- When implementing API key generation, validation, or rotation
- When adding rate limiting to authentication endpoints
- When reviewing or fixing security vulnerabilities in authentication code
- When working with authentication-related database models, migrations, or queries
- When implementing JWT signing, verification, or token expiration logic
- When creating secure credential storage or secret management code

# Backend API Authentication

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle backend API authentication.

## Instructions

For details, refer to the information provided in this file:
[backend API authentication](../../../agent-os/standards/backend/api/authentication.md)

Overview

This skill guides secure implementation of backend API authentication using industry best practices such as token-based auth, OAuth2/OIDC, JWT handling, and robust password security. It is intended for TypeScript backend code that creates or modifies login endpoints, token logic, session management, or any code that handles user credentials and secrets. Follow it to reduce auth-related vulnerabilities and to standardize behavior across services.

How this skill works

The skill inspects authentication-related code paths and recommends concrete changes: token issuance and validation, JWT signing/verification, password hashing and verification, OAuth2/OIDC flows, API key management, and rate limiting for auth endpoints. It focuses on secure defaults (strong hashing, short-lived access tokens, rotating refresh tokens), safe secret handling, and middleware/guard patterns appropriate for TypeScript backends.

When to use it

  • Implementing or modifying login, logout, or token refresh endpoints
  • Writing or updating token generation, signing, or validation logic (JWTs, opaque tokens)
  • Creating or changing password hashing, verification, reset, or storage code
  • Implementing OAuth2/OIDC flows, client credentials, or third-party sign-in
  • Adding authentication middleware, guards, decorators, or rate limiting for auth endpoints

Best practices

  • Use strong, adaptive hashing (bcrypt/argon2) with appropriate cost and never store plain passwords
  • Sign JWTs with asymmetric keys (RS256) or use short expirations and rotate keys regularly
  • Store refresh tokens server-side or use rotating refresh tokens with revocation capability
  • Validate tokens on every request via middleware; avoid trusting client state for authorization
  • Protect auth endpoints with rate limiting, IP monitoring, and account lockout on suspicious activity
  • Keep secrets in secure stores (KMS/Secret Manager) and avoid embedding keys in source code

Example use cases

  • Create a /login endpoint that verifies credentials, returns short-lived access JWT and rotating refresh token
  • Implement middleware that validates JWT signature, checks revocation list, and populates request user context
  • Migrate password storage from SHA1/MD5 to argon2 with a mandatory reset flow for legacy users
  • Add OAuth2 authorization code flow integration with PKCE for web/mobile clients
  • Add rate limiting and exponential backoff to the authentication endpoints to mitigate brute-force attacks

FAQ

Should I store refresh tokens in the database?

Yes. Persist refresh tokens (or their hashed identifiers) to allow revocation and rotation. Store minimal metadata and mark tokens as single-use when rotating.

When should I use JWTs vs opaque tokens?

Use JWTs when you need stateless verification and include claims. Prefer opaque tokens when you require strict server-side revocation or want to avoid long-lived stateless tokens.