Python -- uses WorkOSClient, not WorkOS Skill

Index

| Topic | Reference | Key features | |---|---|---| | AuthKit Next.js | references/authkit-nextjs.md | Proxy/middleware, composable auth, client hooks, session management, eager auth, API key validation | | AuthKit React (SPA) | references/authkit-react.md | Provider setup, sign-in endpoint, multi-org switching, feature flags, token refresh lifecycle | | Node SDK v8 | references/node-sdk-v8.md | PKCE auth, createWorkOS factory, Cloudflare Workers, breaking changes from v7 | | Python & Go SDKs | references/sdk-python-go.md | WorkOSClient (Python), AsyncWorkOSClient, per-package Go SDK |

Quick Reference

AuthKit Next.js -- Proxy vs Middleware

| Next.js version | File | Export | |---|---|---| | 16+ | proxy.ts | authkitProxy() | | <=15 | middleware.ts | authkitMiddleware() |

For composable proxy/middleware, use authkit() + handleAuthkitHeaders():

import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';

export default async function proxy(request: NextRequest) {
  const { session, headers, authorizationUrl } = await authkit(request);
  if (!session.user && authorizationUrl) {
    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl });
  }
  return handleAuthkitHeaders(request, headers);
}

For rewrites, use partitionAuthkitHeaders() + applyResponseHeaders() instead.

Custom State Through Auth Flow

Pass custom data through OAuth via state parameter:

const signInUrl = await getSignInUrl({
  state: JSON.stringify({ teamId: 'team_123', referrer: 'homepage' }),
});

export const GET = handleAuth({
  onSuccess: async ({ user, state }) => {
    const data = state ? JSON.parse(state) : null;
  },
});

Session Refresh Callbacks

const { session, headers } = await authkit(request, {
  onSessionRefreshSuccess: async ({ accessToken, user, impersonator }) => { /* ... */ },
  onSessionRefreshError: async ({ error, request }) => { /* ... */ },
});

AuthKit Client Components

All client-side imports use the /components subpath:

import { AuthKitProvider, Impersonation } from '@workos-inc/authkit-nextjs/components';
import { useAuth, useAccessToken } from '@workos-inc/authkit-nextjs/components';

Node SDK v8 -- Client Types

import { createWorkOS } from '@workos-inc/node';

// Public client (PKCE only, no server APIs)
const pub = createWorkOS({ clientId: 'client_123' });

// Confidential client (full API access)
const srv = createWorkOS({ apiKey: 'sk_...', clientId: 'client_123' });

For Cloudflare Workers: import { WorkOS } from '@workos-inc/node/worker';

PKCE Authentication (Public Clients)

const workos = new WorkOS({ clientId: 'client_123' }); // no apiKey

const { url, state, codeVerifier } =
  await workos.userManagement.getAuthorizationUrlWithPKCE({
    redirectUri: 'myapp://callback',
    provider: 'authkit',
  });

// After callback:
const { accessToken, refreshToken, user } =
  await workos.userManagement.authenticateWithCode({
    code: authCode,
    codeVerifier, // required for PKCE
  });

Key Breaking Changes (v7 to v8)

| Area | Change | |---|---| | Runtime | Node.js 20+ required (was 16+) | | SSO | getAuthorizationUrl options: discriminated union -- specify one of connection, organization, provider | | Directory Sync | User fields (emails, username, jobTitle) moved to customAttributes | | MFA | verifyFactor() renamed to verifyChallenge() | | Vault | All *Secret() methods renamed to *Object() | | PKCE | Always enabled in AuthKit v3 -- remove WORKOS_ENABLE_PKCE env var |

User Management Renames (v7 to v8)

| v7 | v8 | |---|---| | sendMagicAuthCode() | createMagicAuth() | | sendPasswordResetEmail() | createPasswordReset() | | refreshAndSealSessionData() | loadSealedSession() then session.refresh() |

AuthKit React (SPA) Essentials

Wrap app in AuthKitProvider with clientId. Set apiHostname for custom auth domains in production.

import { useAuth } from '@workos-inc/authkit-react';
const { user, signIn, signOut, role, roles, featureFlags, permissions } = useAuth();

// Multi-org switching
const { switchToOrganization } = useAuth();
await switchToOrganization({ organizationId: 'org_123' });

Token refresh control: onBeforeAutoRefresh: () => boolean, onRefreshFailure: ({ signIn }) => void, refreshBufferInterval: number.

Python & Go SDK Patterns

# Python -- uses WorkOSClient, not WorkOS
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_1234", client_id="client_1234")

# Async
from workos import AsyncWorkOSClient

async_client = AsyncWorkOSClient(api_key="sk_1234", client_id="client_1234")

// Go v6 -- per-package configuration, no unified client
import "github.com/workos/workos-go/v6/pkg/sso"
sso.Configure("<API_KEY>", "<CLIENT_ID>")

Reference Files

| File | Contents | |---|---| | authkit-nextjs.md | Proxy migration, composable middleware, client hooks, useAccessToken, session callbacks, eager auth, validateApiKey, saveSession | | authkit-react.md | SPA provider, sign-in endpoint, multi-org, feature flags, getClaims, token refresh, URL helpers | | node-sdk-v8.md | PKCE auth, createWorkOS factory, Cloudflare Workers, all breaking changes v7 to v8, post-v8 additions | | sdk-python-go.md | Python WorkOSClient/AsyncWorkOSClient, Go per-package SDK pattern |

Agent Skills: Python -- uses WorkOSClient, not WorkOS

Install this agent skill to your local

Skill Files