workos-authkit-base

Original：🇺🇸 English

Translated

Architectural reference for WorkOS AuthKit integrations. Fetch README first for implementation details.

1installs

Sourceworkos/cli

Added on2026-02-07

NPX Install

npx skill4agent add workos/cli workos-authkit-base

SKILL.md Content

View Translation Comparison →

WorkOS AuthKit Base Template

First Action: Fetch README

Before any implementation, fetch the framework-specific README:

WebFetch: {sdk-package-name} README from npmjs.com or GitHub

README is the source of truth for: install commands, imports, API usage, code patterns.

Task Structure (Required)

Phase	Task	Blocked By	Purpose
1	preflight	-	Verify env vars, detect framework
2	install	preflight	Install SDK package
3	callback	install	Create OAuth callback route
4	provider	install	Setup auth context/middleware
5	ui	callback, provider	Add sign-in/out UI
6	verify	ui	Build confirmation

Decision Trees

Package Manager Detection

pnpm-lock.yaml? → pnpm
yarn.lock? → yarn
bun.lockb? → bun
else → npm

Provider vs Middleware

Client-side framework? → AuthKitProvider wraps app
Server-side framework? → Middleware handles sessions
Hybrid (Next.js)? → Both may be needed

Callback Route Location

Extract path from

WORKOS_REDIRECT_URI

→ create route at that exact path.

Environment Variables

Variable	Purpose	When Required
`WORKOS_API_KEY`	Server authentication	Server SDKs
`WORKOS_CLIENT_ID`	Client identification	All SDKs
`WORKOS_REDIRECT_URI`	OAuth callback URL	Server SDKs
`WORKOS_COOKIE_PASSWORD`	Session encryption (32+ chars)	Server SDKs

Note: Some frameworks use prefixed variants (e.g.,

NEXT_PUBLIC_*

). Check README.

Verification Checklists

After Install

SDK package installed in node_modules
No install errors in output

After Callback Route

Route file exists at path matching
```
WORKOS_REDIRECT_URI
```
Imports SDK callback handler (not custom OAuth)

After Provider/Middleware

Provider wraps entire app (client-side)
Middleware configured in correct location (server-side)

After UI

Home page shows conditional auth state
Uses SDK functions for sign-in/out URLs

Final Verification

Build completes with exit code 0
No import resolution errors

Error Recovery

Module not found

Verify install completed successfully
Verify SDK exists in node_modules
Re-run install if missing

Build import errors

Delete
```
node_modules
```
, reinstall
Verify package.json has SDK dependency

Invalid redirect URI

Compare route path to
```
WORKOS_REDIRECT_URI
```
Paths must match exactly

Cookie password error

Verify
```
WORKOS_COOKIE_PASSWORD
```
is 32+ characters
Generate new:
```
openssl rand -base64 32
```

Auth state not persisting

Verify provider wraps entire app
Check middleware is in correct location

Critical Rules

Install SDK before writing imports - never create import statements for uninstalled packages
Use SDK functions - never construct OAuth URLs manually
Follow README patterns - SDK APIs change between versions
Extract callback path from env - don't hardcode
```
/auth/callback
```