Design or refactor product authentication setup for web apps and APIs. Use when the user needs to choose hosted, framework-native, platform-native, enterprise- add-on, or self-hosted auth; define sessions vs JWTs; wire OAuth/social login, passkeys, org/member models, callback/cookie environment setup, or SSO/SCIM rollout boundaries before implementation. Not for deeper authorization policy, general security hardening, API contract design, backend test planning, or pure database modeling.
Design or refactor product authentication setup for web apps and APIs. Use when the user needs to choose hosted, framework-native, platform-native, enterprise- add-on, or self-hosted auth; define sessions vs JWTs; wire OAuth/social login, passkeys, org/member models, callback/cookie environment setup, or SSO/SCIM rollout boundaries before implementation. Not for deeper authorization policy, general security hardening, API contract design, backend test planning, or pure database modeling.
allowed-tools
Bash Read Write Edit Glob Grep
compatibility
Best for SaaS, internal tools, B2B web apps, APIs, and fullstack frameworks such as Next.js, React, Node, Python, and Postgres/Supabase-style stacks where auth setup decisions cross frontend, backend, data, deployment, and enterprise customer handoff.
Use this skill when the real job is choosing and structuring product authentication for a real app, not dumping JWT snippets or pretending authentication, authorization, security hardening, and docs are all the same task.
authentication-setup owns the setup layer for:
choosing hosted vs framework-native vs platform-native vs enterprise add-on vs self-hosted auth
deciding session/cookie vs token boundaries
selecting login methods: email/password, magic links, social OAuth, passkeys
defining what user/profile/org/membership data stays app-owned
planning SSO/SCIM, domain mapping, and migration/cutover boundaries
recording callback URLs, cookie domains, preview/staging drift, and rollout notes
Read these support docs before choosing the lane or handoff:
Set up auth for a new web app, SaaS product, admin app, or API-backed product
Decide between Clerk, Auth.js, Better Auth, Supabase Auth, Firebase Auth, Cognito, Keycloak, or similar paths
Add or refactor sessions, cookies, refresh-token strategy, OAuth providers, or passkeys
Define app-owned users, profiles, orgs, memberships, and role boundaries around an auth provider
Add organizations, invites, enterprise SSO, SCIM, or domain verification as the next milestone
Untangle auth boundaries across frontend routes, middleware, backend APIs, and database policy layers
Review whether the current auth stack is too vendor-coupled, too DIY, or too vague to scale safely
When not to use this skill
The main job is authorization policy, permission inheritance, or ABAC/ReBAC modeling → treat it as a dedicated authorization design problem and route contract semantics to api-design
The main job is cookie flags, CSRF, rate limiting, secret handling, abuse prevention, or general vulnerability hardening → use security-best-practices
The main job is API contract/interface design before auth is slotted into the API honestly → use api-design
→ use
The main job is developer-facing reference docs, quickstarts, or API auth docs for consumers
api-documentation
The main job is backend regression coverage, login/callback testing, or role-matrix test planning → use backend-testing
The main job is deeper schema normalization/indexing rather than auth-owned tables and identity boundaries → use database-schema-design
Instructions
Step 1: Classify the auth job before naming vendors
Server sessions / signed cookies for browser-heavy apps, SSR, and middleware-friendly auth state
Stateless JWTs for API-heavy and multi-service traffic where token verification is a first-class requirement
Hybrid when browser sessions and API/machine tokens both matter
Always record:
chosen login methods and why they are needed now
token/session lifetime and refresh strategy
logout/revocation expectations
callback URL and cookie/domain behavior across local, preview, staging, and production
edge/runtime constraints that may change helper availability
Step 5: Model app-owned auth data
Even hosted auth rarely removes the need for local tables.
Usually define at least:
users or profiles
organizations / workspaces if multi-tenant
memberships / roles
invitation, provisioning, or seat state if teams are invited/admin-managed
Record:
the stable user identifier across provider and app DB
which fields stay vendor-owned vs mirrored locally
whether permissions live in claims, local tables, or both
how webhook or sync failures are detected and repaired
If the request slides into broader schema design, route deeper modeling to database-schema-design.
Step 6: Branch enterprise or migration work explicitly
If the request includes SSO, SCIM, domain verification, existing-user linking, provider migration, or self-hosted cutover risk, use enterprise-and-migration-notes.md.
Name these items directly:
whether this is an add-on vs replacement
account-linking and org/domain mapping rules
provisioning / deprovisioning behavior
customer onboarding/support expectations
rollback boundary if the rollout or migration goes wrong
Step 7: Produce an auth setup packet
The output should help the next implementation step succeed.
Preferred packet:
chosen auth lane and why
primary stack recommendation plus fallback
provider/app ownership boundary
session + login model
app-owned data model outline
environment checklist
adjacent route-outs
open risks or migration notes
Output format
Use this structure unless the user asks for another format:
