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

Discovery Priority

When both discovery and endpoint overrides are available, the override values take precedence over discovered values.

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