Configuration Reference

Overview

The AuthrimClientConfig object is passed to createAuthrimClient() to configure the SDK. This page documents all available options and their defaults.

AuthrimClientConfig

import { createAuthrimClient } from '@authrim/core';

const client = await createAuthrimClient({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  crypto: cryptoProvider,
  storage: storageProvider,
  http: httpClient,
  // ... additional options
});

Required Options

Option	Type	Description
`issuer`	`string`	OIDC issuer URL. Used for discovery (`/.well-known/openid-configuration`)
`clientId`	`string`	OAuth 2.0 client ID
`crypto`	`CryptoProvider`	Cryptographic operations provider
`storage`	`AuthrimStorage`	Persistent storage provider
`http`	`HttpClient`	HTTP client provider

Optional Options

Option	Type	Default	Description
`redirectUri`	`string`	—	Default redirect URI for authentication flows
`scopes`	`string[]`	`['openid', 'profile']`	Default scopes for authentication requests
`endpoints`	`EndpointOverrides`	—	Manual endpoint overrides (bypass discovery)
`flowEngine`	`boolean`	—	Enable server-driven UI flows
`discoveryCacheTtlMs`	`number`	`3600000` (1 hour)	Discovery document cache TTL in milliseconds
`refreshSkewSeconds`	`number`	`30`	Seconds before expiry to trigger token refresh
`stateTtlSeconds`	`number`	`600` (10 minutes)	TTL for state/nonce entries in storage
`hashOptions`	`HashOptions`	—	Storage key hashing configuration

EndpointOverrides

Override individual OIDC endpoints. Useful when the authorization server doesn’t support discovery or when you need to point to custom endpoints.

const client = await createAuthrimClient({
  // ...
  endpoints: {
    authorization: 'https://auth.example.com/authorize',
    token: 'https://auth.example.com/token',
    userinfo: 'https://auth.example.com/userinfo',
    revocation: 'https://auth.example.com/revoke',
    endSession: 'https://auth.example.com/logout',
  },
});

Property	Type	Description
`authorization`	`string`	Authorization endpoint URL
`token`	`string`	Token endpoint URL
`userinfo`	`string`	UserInfo endpoint URL
`revocation`	`string`	Token revocation endpoint URL
`endSession`	`string \| null`	End session endpoint URL. Set to `null` to disable server logout

Disabling Server Logout

Set endSession to null to perform local-only logout (no redirect to the authorization server):

const client = await createAuthrimClient({
  // ...
  endpoints: {
    endSession: null,
  },
});

HashOptions

Configure storage key hashing to prevent exposure of issuer and client ID in storage keys.

const client = await createAuthrimClient({
  // ...
  hashOptions: {
    enabled: true,
  },
});

When enabled, storage keys are hashed using SHA-256 so that the actual issuer URL and client ID are not visible in the storage backend.

Configuration Details

`discoveryCacheTtlMs`

Controls how long the OIDC Discovery document is cached in memory. After the TTL expires, the next operation that requires the discovery document will fetch it again.

const client = await createAuthrimClient({
  // ...
  discoveryCacheTtlMs: 3600000, // 1 hour (default)
});

Set to 0 to disable caching (fetch on every use — not recommended for production).

`refreshSkewSeconds`

The number of seconds before token expiration at which the SDK considers the token “expired” and triggers a refresh. This prevents the edge case where a token expires between retrieval and use in an API call.

const client = await createAuthrimClient({
  // ...
  refreshSkewSeconds: 30, // Refresh 30 seconds before expiry (default)
});

A higher value provides more safety margin but triggers more refresh requests
A lower value reduces unnecessary refreshes but increases the risk of using an expired token

`stateTtlSeconds`

The TTL for state and nonce entries stored during the authorization flow. If the user doesn’t complete authentication within this time, the stored state expires and the callback will fail with expired_state.

const client = await createAuthrimClient({
  // ...
  stateTtlSeconds: 600, // 10 minutes (default)
});

`scopes`

Default scopes included in every authorization request. Individual requests can override this.

const client = await createAuthrimClient({
  // ...
  scopes: ['openid', 'profile', 'email'],
});

// Override for a specific request
const { url } = await client.buildAuthorizationUrl({
  redirectUri: 'https://myapp.com/callback',
  scope: 'openid profile email offline_access',
});

Default Values Summary

Option	Default
`scopes`	`['openid', 'profile']`
`discoveryCacheTtlMs`	`3600000` (1 hour)
`refreshSkewSeconds`	`30`
`stateTtlSeconds`	`600` (10 minutes)

Resolved Configuration

Internally, the SDK resolves the provided configuration into a ResolvedConfig object with all defaults applied. This happens automatically during createAuthrimClient().

Example: Full Configuration

const client = await createAuthrimClient({
  // Required
  issuer: 'https://auth.example.com',
  clientId: 'my-spa-app',
  crypto: webCryptoProvider,
  storage: localStorageProvider,
  http: fetchHttpClient,

  // Optional
  redirectUri: 'https://myapp.com/callback',
  scopes: ['openid', 'profile', 'email'],
  discoveryCacheTtlMs: 1800000,   // 30 minutes
  refreshSkewSeconds: 60,          // 1 minute before expiry
  stateTtlSeconds: 300,            // 5 minutes
  hashOptions: {
    enabled: true,
  },
  endpoints: {
    // Override only specific endpoints
    revocation: 'https://auth.example.com/oauth/revoke',
  },
});

Next Steps

Installation & Setup — Get started with the SDK
Provider Interfaces — Implement custom providers
Authorization Code Flow — Start authenticating