api-security-auth-pattern

API Security & Auth Skill

Design complete authentication and security layers for any API.

---

Auth Pattern Selection Guide

Use Case	Recommended Pattern
User-facing web/mobile app	OAuth 2.0 + JWT (Authorization Code + PKCE)
Server-to-server (M2M)	OAuth 2.0 Client Credentials + JWT
Simple 3rd party access	API Key (header)
High-security enterprise	mTLS + short-lived JWT
Microservices internal	JWT propagation or service mesh (mTLS)
Webhook verification	HMAC-SHA256 signature header

---

OAuth 2.0 Flow Endpoints

POST /auth/oauth/authorize      — redirect user to consent screen
POST /auth/oauth/token          — exchange code for tokens
POST /auth/oauth/token/refresh  — refresh access token
POST /auth/oauth/revoke         — revoke token
GET  /auth/oauth/userinfo       — get user profile from token

Token endpoint request

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "https://app.example.com/callback",
  "client_id": "CLIENT_ID",
  "code_verifier": "PKCE_VERIFIER"
}

Token response

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_...",
  "scope": "read write"
}

---

JWT Design

Header: { "alg": "RS256", "typ": "JWT" }

Claims payload:

{
  "sub": "user-uuid",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1700000000,
  "iat": 1699996400,
  "jti": "unique-token-id",
  "roles": ["admin", "editor"],
  "tenant_id": "org-uuid",
  "scope": "read:users write:posts"
}

Validation checklist: verify iss, aud, exp, nbf; reject alg: none; check token revocation list.

---

RBAC Design

Roles:   super_admin > admin > editor > viewer > guest
Resources: users, posts, settings, billing, reports

Permission matrix:
              users   posts  settings  billing  reports
super_admin:  CRUD    CRUD   CRUD      CRUD     R
admin:        CRUD    CRUD   R         R        R
editor:       R       CRUD   -         -        R
viewer:       R       R      -         -        R
guest:        -       R(pub) -         -        -