building-api-authentication_skill

Overview

This skill automates designing and implementing secure API authentication systems using OAuth2, JWTs, API keys, and session management. It guides you from threat-informed requirements to middleware, token handling, and test coverage. The goal is practical, production-ready auth layers that integrate with common frameworks and OpenAPI documentation.

How this skill works

The skill inspects API surface and authentication requirements, then scaffolds endpoint auth flows, middleware, token issuance, validation, and revocation patterns. It generates or suggests code for bearer token handling, API key verification, OAuth2/OIDC flows (including PKCE), session stores, and integration points for databases and identity providers. It also recommends OpenAPI artifacts and test scenarios to validate auth behavior.

When to use it

• Adding authentication to a new or existing API
• Choosing between OAuth2, JWT, API keys, or session approaches
• Implementing token issuance, refresh, and revocation logic
• Securing microservice-to-microservice calls and service accounts
• Preparing compliance-ready auth controls (audit logs, rotation, expiry)

Best practices

• Follow least-privilege and scope-based authorization, issuing tokens with minimal permissions.
• Use short-lived access tokens and refresh tokens; enforce token revocation and rotation.
• Always transmit credentials and tokens over TLS; use secure cookie attributes for session cookies.
• Validate tokens server-side (signature, issuer, audience, expiry) and check revocation lists for critical flows.
• Log auth events, monitor failed attempts and rate-limit endpoints to mitigate brute force attacks.

Example use cases

• Public REST API: issue and validate API keys for rate-limited client tiers.
• Single-page or mobile apps: implement OAuth2 Authorization Code with PKCE and short-lived JWT access tokens.
• Backend services: use signed JWTs or mTLS for service-to-service authentication with scoped permissions.
• Legacy web apps: migrate session stores to secure, HttpOnly cookies and add CSRF protections.
• Hybrid setups: combine API keys for machine clients and OAuth2 for user-driven flows, centralizing token validation.