WorkOS AuthKit Session

https://github.com/workos/authkit-session
Admin
WorkOS AuthKit Session is a toolkit for building framework integrations that handles JWT...
Tokens:56,360
Snippets:382
Trust Score:10
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install @workos/authkit-session with pnpm

Source: https://github.com/workos/authkit-session/blob/main/README.md

Install the @workos/authkit-session package using pnpm.

```bash
pnpm add @workos/authkit-session
```

--------------------------------

### getConfigurationProvider usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example of retrieving the provider and swapping the source at runtime or validating to fail fast at startup.

```typescript
const provider = getConfigurationProvider();
provider.setValueSource(mySource);   // swap the source at runtime
provider.validate();                  // fail fast at startup
```

--------------------------------

### getSession usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example of retrieving a session and logging the user email and access token when the session exists.

```typescript
const session = await authService.getSession(request);
if (session) {
  console.log(session.user.email, session.accessToken);
}
```

--------------------------------

### createSignUp usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Example usage of `createSignUp` with a `loginHint` option, extracting the `url` from the returned promise.

```ts
const { url } = await operations.createSignUp({ loginHint: 'user@example.com' });
```

--------------------------------

### createSignUp signature and usage

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Signature and usage example for createSignUp. It passes screenHint: 'sign-up' to createAuthorization. The example shows passing a redirectUri option.

```ts
async createSignUp(
    response: TResponse | undefined,
    options: Omit<GetAuthorizationUrlOptions, 'screenHint'> = {},
  ): Promise<CreateAuthorizationResult<TResponse>>
```

```ts
const { url, headers } = await authService.createSignUp(response, {
  redirectUri: 'https://app.example.com/auth/callback',
});
```

--------------------------------

### getLogoutUrl usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Example usage of getLogoutUrl with a returnTo option.

```typescript
const logoutUrl = operations.getLogoutUrl(sessionId, { returnTo: '/' });
```

--------------------------------

### getConfig usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example of calling getConfig to retrieve the apiKey and cookieName. The cookieName returns 'wos-session' if unset.

```typescript
const apiKey = getConfig('apiKey');
const cookieName = getConfig('cookieName'); // 'wos-session' if unset
```

--------------------------------

### saveSession usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example of saving a session by appending Set-Cookie headers to the response.

```typescript
const { headers } = await authService.saveSession(response, refreshedSessionData);
for (const v of headers?.['Set-Cookie'] ?? []) {
  response.headers.append('Set-Cookie', v);
}
```

--------------------------------

### createSignIn signature and usage

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Signature and usage example for createSignIn. It passes screenHint: 'sign-in' to createAuthorization. The example shows a typical redirect response using the returned url and headers.

```ts
async createSignIn(
    response: TResponse | undefined,
    options: Omit<GetAuthorizationUrlOptions, 'screenHint'> = {},
  ): Promise<CreateAuthorizationResult<TResponse>>
```

```ts
const { url, headers, cookieName } = await authService.createSignIn(response, {
  returnPathname: '/app',
});
return new Response(null, { status: 302, headers: { ...headers, Location: url } });
```

--------------------------------

### Minimal configuration with configure()

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/configuration.md

Sets up the AuthKit session with required environment variables and cookie settings. Use this as the starting point for initializing the session in your application. The cookiePassword must be at least 32 characters long.

```typescript
import { configure } from '@workos/authkit-session';

configure({
  clientId: process.env.WORKOS_CLIENT_ID,
  apiKey: process.env.WORKOS_API_KEY,
  redirectUri: 'https://app.example.com/auth/callback',
  cookiePassword: 'at-least-32-characters-long-secret-value',
  cookieMaxAge: 60 * 60 * 24 * 30, // 30 days
  cookieSameSite: 'lax',
  cookieName: 'my-session',
  cookieDomain: '.example.com',
});
```

--------------------------------

### Usage example for validateAndRefresh

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example showing how to call validateAndRefresh with force and organizationId, and persist the refreshed session using encryptSession.

```typescript
const result = await core.validateAndRefresh(session, { force: true, organizationId: 'org_x' });
if (result.refreshed) {
  const encrypted = await core.encryptSession(result.session); // persist!
}
```

--------------------------------

### Usage example with configure, setValueSource, and getConfig

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/ConfigurationProvider.md

Shows how to programmatically configure the provider, set a custom value source, and retrieve the merged config. Comments illustrate precedence: programmatic clientId, source apiKey, defaults for cookieName and apiHttps.

```typescript
const provider = new ConfigurationProvider();
provider.configure({ clientId: 'client_x' });
provider.setValueSource((key) => ({ WORKOS_API_KEY: 'sk_test' })[key]);

const cfg = provider.getConfig();
// cfg.clientId === 'client_x' (programmatic), cfg.apiKey === 'sk_test' (source),
// cfg.cookieName === 'wos-session' (default), cfg.apiHttps === true (default)
```

--------------------------------

### validateConfig usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example of calling validateConfig in a try-catch block to fail fast at startup, logging the error message and exiting the process.

```typescript
// Fail fast at startup instead of on the first request.
try {
  validateConfig();
} catch (error) {
  console.error(error.message);
  process.exit(1);
}
```

--------------------------------

### configure with programmatic config

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example of overload 2: merges programmatic config into the singleton. Environment variables still take precedence over these values.

```ts
// Overload 2
configure({
  clientId: 'client_123',
  apiKey: 'sk_...',
  redirectUri: 'https://app.example.com/auth/callback',
  cookiePassword: 'a-32+-character-long-cookie-encryption-secret',
});
```

--------------------------------

### verifyCallbackState usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example of calling verifyCallbackState with state from URL and cookie value, then destructuring codeVerifier and returnPathname from the result.

```typescript
const state = await core.verifyCallbackState({
  stateFromUrl: url.searchParams.get('state') ?? undefined,
  cookieValue: await storage.getCookie(request, cookieName),
});
const { codeVerifier, returnPathname } = state;
```

--------------------------------

### Using createAuthorization

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Example usage of createAuthorization. It passes returnPathname, screenHint, and state, then stores the sealed state cookie and returns the authorization URL.

```ts
const { url, sealedState, cookieName, cookieOptions } =
  await operations.createAuthorization({
    returnPathname: '/dash',
    screenHint: 'sign-in',
    state: 'my-custom-state',
  });
await storage.setCookie(response, cookieName, sealedState, cookieOptions);
return url;
```

--------------------------------

### validateConfig error message example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example output of the error message thrown by validateConfig when required environment variables are missing or invalid. Shows the format with bullet points and a link to the WorkOS Dashboard.

```text
AuthKit configuration error. Missing or invalid environment variables:

  • WORKOS_CLIENT_ID is required
  • WORKOS_API_KEY is required
  • WORKOS_COOKIE_PASSWORD must be at least 32 characters (currently 12)

Set these environment variables or call configure() with the required values.
Get your values from the WorkOS Dashboard: https://dashboard.workos.com
```

--------------------------------

### Using verifyToken and refreshTokens

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example usage: checks if the access token is valid, and if not, refreshes the session using the refresh token.

```typescript
const valid = await core.verifyToken(session.accessToken);
if (!valid) {
  await core.refreshTokens(session.refreshToken);
}
```

--------------------------------

### Use getWorkOS to call WorkOS API

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example usage of getWorkOS to access the WorkOS client and call userManagement.getUser directly.

```ts
const user = await authService
  .getWorkOS()
  .userManagement.getUser({ userId });
```

--------------------------------

### Lazy singleton example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Demonstrates that repeated calls to getWorkOS return the same instance.

```typescript
// Lazy singleton: repeated calls return the same instance.
import { getWorkOS } from '@workos/authkit-session';
console.log(getWorkOS() === getWorkOS()); // true
```

--------------------------------

### configure with custom value source

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Example of overload 3: merges config and sets a custom value source, useful for Cloudflare Workers-style environments.

```ts
// Overload 3 — Cloudflare Workers-style custom source
configure({ clientId: 'client_123' }, (key) => myEnvStore[key]);
```

--------------------------------

### Encrypt session with encryptSession

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example usage of encryptSession to encrypt a session object, returning the encrypted string.

```ts
const encrypted = await core.encryptSession(session);
```

--------------------------------

### Example usage of refreshTokens with error handling

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Shows how to call refreshTokens with an organization ID and context, and how to catch TokenRefreshError to access userId, sessionId, and cause.

```typescript
try {
  const { accessToken, refreshToken, user, impersonator } =
    await core.refreshTokens(session.refreshToken, 'org_123', {
      userId: session.user.id,
      sessionId,
    });
} catch (error) {
  if (error instanceof TokenRefreshError) {
    console.error(error.userId, error.sessionId, error.cause);
  }
}
```

--------------------------------

### Adapter usage of handleCallback

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example of calling handleCallback from an adapter. It extracts the code and state from the request URL, then appends each Set-Cookie header individually (never comma-joined) before redirecting to the returnPathname.

```ts
const url = new URL(request.url);
const result = await authService.handleCallback(request, response, {
  code: url.searchParams.get('code') ?? '',
  state: url.searchParams.get('state') ?? undefined,
});
// Adapters MUST append each Set-Cookie as its own header — never comma-join.
const setCookie =
  result.headers?.['Set-Cookie'] ?? result.headers?.['set-cookie'];
for (const v of Array.isArray(setCookie) ? setCookie : [setCookie]) {
  response.headers.append('Set-Cookie', v);
}
return redirect(result.returnPathname);
```

--------------------------------

### signOut signature and usage

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Terminates the WorkOS session server-side and returns a logout URL plus the local session-clear result. The first block shows the signature; the second shows a usage example that redirects to the logout URL.

```ts
async signOut(
    sessionId: string,
    options?: { returnTo?: string },
  ): Promise<{
    logoutUrl: string;
    response?: TResponse;
    headers?: HeadersBag;
  }>
```

```ts
const { logoutUrl, headers } = await authService.signOut(sessionId, {
  returnTo: 'https://app.example.com',
});
return new Response(null, {
  status: 302,
  headers: { ...headers, Location: logoutUrl },
});
```

--------------------------------

### decryptSession usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example of calling decryptSession with a cookie value to obtain the session.

```typescript
const session = await core.decryptSession(cookieValue);
```

--------------------------------

### constructor

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Creates an AuthOperations instance with the required dependencies.

```APIDOC
## Constructor

### Description
Creates an AuthOperations instance with the required dependencies.

### Signature
```ts
constructor(
    core: AuthKitCore,
    client: WorkOS,
    config: AuthKitConfig,
    encryption: SessionEncryption,
  )
```

### Parameters
- **core** (AuthKitCore) - Required - Business-logic core (refresh + encryption)
- **client** (WorkOS) - Required - `@workos-inc/node` client
- **config** (AuthKitConfig) - Required - Resolved configuration
- **encryption** (SessionEncryption) - Required - Seal adapter (forwarded to URL generation for state sealing)
```

--------------------------------

### constructor(config, storage, client, encryption)

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Creates an AuthService instance with resolved configuration, session storage adapter, WorkOS client, and encryption implementation. Prefer createAuthService unless direct dependency injection is needed.

```APIDOC
## constructor(config, storage, client, encryption)

### Description
Creates an AuthService instance with the provided configuration, storage adapter, WorkOS client, and encryption implementation. The constructor creates internal AuthKitCore and AuthOperations instances.

### Method
constructor

### Signature
```ts
constructor(
    config: AuthKitConfig,
    storage: SessionStorage<TRequest, TResponse>,
    client: WorkOS,
    encryption: SessionEncryption,
  )
```

### Parameters
- **config** (AuthKitConfig) - Required - Resolved configuration (see configuration.md)
- **storage** (SessionStorage<TRequest, TResponse>) - Required - Adapter providing cookie/session primitives
- **client** (WorkOS) - Required - @workos-inc/node client (see getWorkOS)
- **encryption** (SessionEncryption) - Required - Seal/unseal implementation (e.g. sessionEncryption)

### Notes
Prefer createAuthService unless you need direct dependency injection.
```

--------------------------------

### createSignUp

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Generates an authorization URL for the sign-up flow. The screenHint is automatically set to 'sign-up' and cannot be overridden.

```APIDOC
## `createSignUp`

### Description
Creates an authorization URL for the sign-up flow. The `screenHint` is forced to `'sign-up'` and cannot be overridden.

### Method
- **createSignUp** (async)

### Signature
```ts
async createSignUp(
  options: Omit<GetAuthorizationUrlOptions, 'screenHint'> = {},
): Promise<GeneratedAuthorizationUrl>
```

### Parameters
#### options (object, optional)
- **loginHint** (string, optional) - A hint to pre-fill the email address on the sign-up page.
- **screenHint** - Not allowed; always overridden to `'sign-up'`.

### Returns
- **Promise<GeneratedAuthorizationUrl>** - Resolves to an object containing the generated authorization URL.

### Example
```ts
const { url } = await operations.createSignUp({ loginHint: 'user@example.com' });
```
```

--------------------------------

### Sign-in and callback with PKCE verifier

Source: https://github.com/workos/authkit-session/blob/main/README.md

Shows the sign-in and callback flow using createSignIn and handleCallback. The library writes the verifier cookie and returns the URL and headers; the callback reads the verifier, byte-compares, and exchanges the code.

```typescript
// Sign in: library writes the verifier cookie via storage, returns the URL + headers
const { url, headers } = await authService.createSignIn(response, {
  returnPathname: '/dashboard',
});
return new Response(null, {
  status: 302,
  headers: { ...headers, Location: url },
});

// Callback: library reads the verifier via storage, byte-compares, then exchanges
await authService.handleCallback(request, response, {
  code,
  state, // from URL
});
```

--------------------------------

### refreshSession usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Example usage of refreshSession with an organization ID, then persisting the encrypted session via AuthService.saveSession and logging the resulting organization ID.

```typescript
const { auth, encryptedSession } = await operations.refreshSession(session, 'org_abc');
const { headers } = await authService.saveSession(response, encryptedSession);
console.log(auth.organizationId); // 'org_abc'
```

--------------------------------

### Usage example for getPKCECookieNameForState

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/pkce-helpers.md

Example usage of getPKCECookieNameForState to retrieve the cookie name for a given sealed state. The output is a deterministic name with the format wos-auth-verifier-<8-hex-chars>.

```ts
import { getPKCECookieNameForState } from '@workos/authkit-session';

// Same input → same name; used to locate/clear the right cookie.
const name = getPKCECookieNameForState(sealedState);
console.log(name); // wos-auth-verifier-<8-hex-chars>
```

--------------------------------

### createSignUp method signature

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Creates a sign-up authorization URL. Forwards `{ ...options, screenHint: 'sign-up' }` to `createAuthorization`. The `screenHint` option cannot be overridden.

```ts
async createSignUp(
    options: Omit<GetAuthorizationUrlOptions, 'screenHint'> = {},
  ): Promise<GeneratedAuthorizationUrl>
```

--------------------------------

### Using getWorkOS to fetch a user

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Shows how to obtain the WorkOS client and call userManagement.getUser.

```typescript
const client = getWorkOS();
const user = await client.userManagement.getUser({ userId });
```

--------------------------------

### createAuthorization usage example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example usage of createAuthorization to generate a redirect response. The returned headers are spread into a 302 Response with the Location header set to the authorization URL.

```typescript
const { url, headers } = await authService.createAuthorization(response, {
  returnPathname: '/dashboard',
  organizationId: 'org_123',
});
return new Response(null, { status: 302, headers: { ...headers, Location: url } });
```

--------------------------------

### getCookie implementation example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/CookieSessionStorage.md

Example implementation of getCookie that reads the 'cookie' header, splits it by ';', and returns the URL-decoded value for the matching cookie name. Returns null if the header is missing or the cookie is not found.

```typescript
export class MyStorage extends CookieSessionStorage<Request, Response> {
  async getCookie(request: Request, name: string): Promise<string | null> {
    const header = request.headers.get('cookie');
    if (!header) return null;
    for (const part of header.split(';')) {
      const [k, ...rest] = part.trim().split('=');
      if (k === name) return decodeURIComponent(rest.join('='));
    }
    return null;
  }
}
```

--------------------------------

### Configure @workos/authkit-session programmatically

Source: https://github.com/workos/authkit-session/blob/main/README.md

Programmatic configuration alternative to environment variables. Requires the same values as the environment variables.

```typescript
import { configure } from '@workos/authkit-session';

configure({
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  redirectUri: 'https://yourdomain.com/auth/callback',
  cookiePassword: 'must-be-at-least-32-characters-long-secret',
});
```

--------------------------------

### createAuthorization(response, options?)

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Creates an authorization URL by delegating to AuthOperations.createAuthorization, which seals the PKCE state and builds the WorkOS URL. Writes the verifier cookie via storage.setCookie and returns the URL, response, headers, and cookie name.

```APIDOC
## createAuthorization(response, options?)

### Description
Creates an authorization URL by delegating to AuthOperations.createAuthorization, which seals the PKCE state and builds the WorkOS URL. Writes the verifier cookie via storage.setCookie and returns the URL, response, headers, and cookie name.

### Method
async createAuthorization(response: TResponse | undefined, options: GetAuthorizationUrlOptions = {}): Promise<CreateAuthorizationResult<TResponse>>

### Parameters
- **response** (TResponse | undefined) - Required - Response to attach the verifier cookie to
- **options** (GetAuthorizationUrlOptions) - Optional - See types.md#getauthorizationurloptions

### Return
`CreateAuthorizationResult<TResponse>` — `{ url, response?, headers?, cookieName }`

### Throws
- **PKCEPayloadTooLargeError** - When `options.state` > 2048 UTF-8 bytes or the serialized verifier cookie > 3800 bytes

### Request Example
```ts
const { url, headers } = await authService.createAuthorization(response, {
  returnPathname: '/dashboard',
  organizationId: 'org_123',
});
return new Response(null, { status: 302, headers: { ...headers, Location: url } });
```
```

--------------------------------

### applyHeaders override example

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/CookieSessionStorage.md

Example override of applyHeaders that creates a new Response (or reuses the existing one) and appends the provided headers. Returns the mutated response, which the storage methods will then return instead of a headers bag.

```typescript
protected async applyHeaders(
  response: Response | undefined,
  headers: Record<string, string | string[]>,
): Promise<{ response: Response }> {
  const newResponse = response
    ? new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: new Headers(response.headers),
      })
    : new Response();
  for (const [key, value] of Object.entries(headers)) {
    for (const v of Array.isArray(value) ? value : [value]) {
      newResponse.headers.append(key, v);
    }
  }
  return { response: newResponse };
}
```

--------------------------------

### clearPendingVerifier signature and error-path usage

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Signature and usage example for clearPendingVerifier. It derives the per-flow cookie name via getPKCECookieNameForState(state) and emits a delete Set-Cookie. The example shows error-path cleanup when handleCallback throws. state is required since 0.5.0.

```ts
async clearPendingVerifier(
    response: TResponse | undefined,
    options: { state: string; redirectUri?: string },
  ): Promise<{ response?: TResponse; headers?: HeadersBag }>
```

```ts
try {
  await authService.handleCallback(request, response, { code, state });
} catch (error) {
  if (state) {
    await authService.clearPendingVerifier(response, { state }); // error-path cleanup
  }
  throw error;
}
```

--------------------------------

### Basic usage: create early, configure later

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/createAuthService.md

Shows how to create the auth service at module scope before configure() is called. The sessionStorageFactory uses a custom MyStorage class. configure() is called later in server bootstrap. The first use triggers lazy init, so configure() must have already run.

```typescript
import { createAuthService, configure, CookieSessionStorage } from '@workos/authkit-session';

// Module scope — runs before configure() is called in server startup.
export const authService = createAuthService({
  sessionStorageFactory: config => new MyStorage(config),
});

// Later, in your server bootstrap:
configure({
  clientId: env.WORKOS_CLIENT_ID,
  apiKey: env.WORKOS_API_KEY,
  redirectUri: env.WORKOS_REDIRECT_URI,
  cookiePassword: env.WORKOS_COOKIE_PASSWORD,
});

// First use triggers lazy init; configure() has already run.
const { auth } = await authService.withAuth(request);
```

--------------------------------

### validateAndRefresh

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Documentation for the validateAndRefresh method, including signature, parameters, return type, behavior, and example usage.

```APIDOC
## `validateAndRefresh`

### Description
Validates the current session and refreshes it if necessary. Returns the validation result, the (possibly refreshed) session, and the parsed claims.

### Method
`validateAndRefresh`

### Signature
```ts
async validateAndRefresh<TCustomClaims = CustomClaims>(
    session: Session,
    options?: { force?: boolean; organizationId?: string },
  ): Promise<{
    valid: boolean;
    refreshed: boolean;
    session: Session;
    claims: BaseTokenClaims & TCustomClaims;
  }>
```

### Parameters
- `session` (Session) - Required - Current session with access + refresh tokens
- `options.force` (boolean) - Optional - Force refresh even when the token is valid (org switching). Default: `false`
- `options.organizationId` (string) - Optional - Explicit org; precedence: explicit > extracted from token claims (`org_id`). Default: `undefined`
- `TCustomClaims` (type param) - Optional - Claims generic. Default: `CustomClaims`

### Return
Returns an object with:
- `valid` (boolean) - Whether the session is valid
- `refreshed` (boolean) - Whether the session was refreshed
- `session` (Session) - The original session unless `refreshed`
- `claims` (BaseTokenClaims & TCustomClaims) - Claims parsed from the (possibly new) access token

### Behavior
- Token valid + not forced → `{ valid: true, refreshed: false, session, claims }`.
- Otherwise refreshes via `refreshTokens`. Org resolution: explicit `organizationId` > `org_id` extracted from the still-valid token's claims; if the token is unparseable, refresh proceeds without org context (fail-soft).
- Session ID is extracted from `sid` (works on expired tokens) and passed as refresh error context.

### Throws
- `TokenRefreshError` if refresh fails (see `refreshTokens`).

### Example
```ts
const result = await core.validateAndRefresh(session, { force: true, organizationId: 'org_x' });
if (result.refreshed) {
  const encrypted = await core.encryptSession(result.session); // persist!
}
```
```

--------------------------------

### createWorkOSInstance internals

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Creates a new WorkOS client with configuration from getConfig. Requires apiKey, defaults apiHostname to 'api.workos.com' and https to true.

```typescript
const apiKey = getConfig('apiKey');
const options = {
  apiHostname: getConfig('apiHostname'),   // default 'api.workos.com'
  https: getConfig('apiHttps'),            // default true
  port: getConfig('apiPort'),
  appInfo: {
    name: 'authkit-session',
    version: pkg.version,                   // 0.7.1 from package.json
  },
};
return new WorkOS(apiKey, options);
```

--------------------------------

### Error handling for handleCallback

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example of handling errors from handleCallback. It catches OAuthStateMismatchError and PKCECookieMissingError to redirect to a login error page, and rethrows other errors.

```ts
try {
  const result = await authService.handleCallback(request, response, {
    code,
    state,
  });
  console.log('custom state:', result.state);
} catch (error) {
  // Types narrow via instanceof — see errors.md
  if (error instanceof OAuthStateMismatchError || error instanceof PKCECookieMissingError) {
    return redirect('/login?error=verify-failed');
  }
  throw error;
}
```

--------------------------------

### Decode JWT claims with parseTokenClaims

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example usage of parseTokenClaims to decode JWT claims and access BaseTokenClaims fields like sid and org_id.

```ts
const claims = core.parseTokenClaims(accessToken);
console.log(claims.sid, claims.org_id); // BaseTokenClaims fields
```

--------------------------------

### Proactive refresh with isTokenExpiring

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthKitCore.md

Example usage of isTokenExpiring to proactively refresh tokens before expiry. It checks with a 60-second buffer and calls refreshTokens if expiring.

```ts
if (core.isTokenExpiring(accessToken, 60)) {
  const { refreshToken } = await core.refreshTokens(session.refreshToken);
  console.log('refreshed proactively');
}
```

--------------------------------

### Create AuthService with createAuthService

Source: https://github.com/workos/authkit-session/blob/main/README.md

Create an AuthService instance using the custom storage adapter. The sessionStorageFactory receives configuration and returns a new storage instance.

```typescript
import { createAuthService } from '@workos/authkit-session';

export const authService = createAuthService({
  sessionStorageFactory: config => new MyFrameworkStorage(config),
});
```

--------------------------------

### createSignIn

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthOperations.md

Generates an authorization URL for the sign-in flow. The screenHint is automatically set to 'sign-in' and cannot be overridden.

```APIDOC
## `createSignIn`

### Description
Creates an authorization URL for the sign-in flow. The `screenHint` is forced to `'sign-in'` and cannot be overridden.

### Method
- **createSignIn** (async)

### Signature
```ts
async createSignIn(
  options: Omit<GetAuthorizationUrlOptions, 'screenHint'> = {},
): Promise<GeneratedAuthorizationUrl>
```

### Parameters
#### options (object, optional)
- **loginHint** (string, optional) - A hint to pre-fill the email address on the sign-in page.
- **screenHint** - Not allowed; always overridden to `'sign-in'`.

### Returns
- **Promise<GeneratedAuthorizationUrl>** - Resolves to an object containing the generated authorization URL.

### Example
```ts
const { url } = await operations.createSignIn({ loginHint: 'user@example.com' });
```
```

--------------------------------

### AuthUrlOptions interface

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/types.md

Options for building an authorization URL. `returnPathname` is sanitized and returned from `handleCallback`; `redirectUri` overrides `config.redirectUri` and is persisted in the sealed state. `state` is round-tripped through `handleCallback` and must be ≤ 2048 UTF-8 bytes; the total sealed payload is capped by the 3800-byte serialized-cookie guard, and exceeding limits throws `PKCEPayloadTooLargeError` at sign-in time.

```ts
export interface AuthUrlOptions {
  returnPathname?: string;
  redirectUri?: string;
  organizationId?: string;
  loginHint?: string;
  prompt?: 'login' | 'none' | 'consent' | 'select_account';
  /**
   * Custom state to pass through the OAuth flow. Returned in handleCallback.
   * Bounded at 2048 UTF-8 bytes. ... Values over the supported limit throw
   * `PKCEPayloadTooLargeError` at sign-in time. ...
   */
  state?: string;
}
```

--------------------------------

### withAuth usage - redirect on unauthenticated

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example of using withAuth to check authentication and redirect unauthenticated users. After the check, TypeScript narrows the type so claims are accessible.

```typescript
const { auth, refreshedSessionData } = await authService.withAuth(request);

if (!auth.user) {
  return redirect('/login');
}
// TypeScript narrows: sessionId, accessToken, claims.all exist here.
const sid = auth.claims.sid;
```

--------------------------------

### Direct access with AuthKitCore and AuthOperations

Source: https://github.com/workos/authkit-session/blob/main/README.md

Shows direct access to the AuthKit primitives for maximum control. Imports AuthKitCore, AuthOperations, getConfigurationProvider, getWorkOS, and sessionEncryption, then instantiates core and operations for advanced use.

```typescript
import {
  AuthKitCore,
  AuthOperations,
  getConfigurationProvider,
  getWorkOS,
  sessionEncryption,
} from '@workos/authkit-session';

const config = getConfigurationProvider().getConfig();
const client = getWorkOS();
const core = new AuthKitCore(config, client, sessionEncryption);
const operations = new AuthOperations(core, client, config, sessionEncryption);

// Use core.validateAndRefresh(), core.encryptSession(), etc.
```

--------------------------------

### clearSession signature and usage

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Clears the local session by emitting a Set-Cookie with Max-Age=0 for the session cookie. The first block shows the method signature; the second shows a usage example that logs out locally.

```ts
async clearSession(
    response: TResponse,
  ): Promise<{ response?: TResponse; headers?: HeadersBag }>
```

```ts
await authService.clearSession(response); // logs out locally
```

--------------------------------

### getConfig

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/config.md

Retrieves a configuration value by key, resolving from environment variables, programmatic config, or defaults. Throws an error if a required key is missing.

```APIDOC
## getConfig

### Description
Retrieves a configuration value by key, resolving from environment variables, programmatic config, or defaults. Throws an error if a required key is missing.

### Method
N/A - This is a TypeScript function, not an HTTP endpoint.

### Endpoint
N/A - This is a TypeScript function, not an HTTP endpoint.

### Parameters
#### Function Parameters
- **key** (`K extends keyof AuthKitConfig`) - Required - One of `clientId` | `apiKey` | `redirectUri` | `cookiePassword` | `apiHostname` | `apiHttps` | `apiPort` | `cookieMaxAge` | `cookieSameSite` | `cookieName` | `cookieDomain`

### Request Example
```ts
const apiKey = getConfig('apiKey');
const cookieName = getConfig('cookieName'); // 'wos-session' if unset
```

### Response
#### Success Response
- **Return** (type-converted value) - The resolved configuration value.

#### Error Response
- **Error** (`Error`) - Throws `Error('Missing required configuration value for <key> (WORKOS_<KEY>).')` when the key is required (`clientId`, `apiKey`, `redirectUri`, `cookiePassword`) and absent.

#### Response Example
```ts
const apiKey = getConfig('apiKey');
const cookieName = getConfig('cookieName'); // 'wos-session' if unset
```
```

--------------------------------

### With custom client and encryption factories

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/createAuthService.md

Shows how to provide a custom clientFactory that creates a WorkOS instance with custom options like apiHostname, https, and appInfo. The sessionStorageFactory uses a custom MyFrameworkStorage. The encryptionFactory is not provided, so it defaults to the built-in sessionEncryption.

```typescript
import { createAuthService } from '@workos/authkit-session';
import { WorkOS } from '@workos-inc/node';

export const authService = createAuthService({
  sessionStorageFactory: config => new MyFrameworkStorage(config),
  clientFactory: config =>
    new WorkOS(config.apiKey, {
      apiHostname: config.apiHostname,
      https: config.apiHttps,
      appInfo: { name: 'my-app', version: '1.0.0' },
    }),
});
```

--------------------------------

### Clear stale PKCE verifier cookies

Source: https://github.com/workos/authkit-session/blob/main/_autodocs/api-reference/AuthService.md

Example usage of clearPendingVerifierByName to clear stale PKCE verifier cookies. It selects stale cookie names with selectStalePKCEVerifierCookieNames, then iterates and calls clearPendingVerifierByName for each, applying the returned headers.

```ts
const stale = selectStalePKCEVerifierCookieNames(Object.keys(cookies), {
  keep: newCookieName,
});
for (const name of stale) {
  const { headers } = await authService.clearPendingVerifierByName(response, {
    cookieName: name,
  });
  // apply headers...
}
```
Tokens:
Raw