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']	Resolved default scopes. Current flow helpers accept scope per request and default to 'openid profile'
endpoints	EndpointOverrides	—	Manual endpoint overrides (bypass discovery)
flowEngine	boolean	false	Enable server-driven UI flows when both SDK and server support them
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	{ hashLength: 16 }	Storage key hash length configuration
dpop	DPoPOptions	{ tokenRequests: false, algorithm: 'ES256' }	DPoP behavior for token endpoint requests and proof signing

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: {
    hashLength: 16,
  },
});

Storage keys are derived from SHA-256 hashes of the normalized issuer and client ID. hashLength controls how many base64url characters are kept. The default 16 is 96 bits; use 22 for 132 bits when you want a lower collision risk.

DPoPOptions

Configure DPoP behavior for token endpoint requests. Core clients keep this disabled by default because the SDK is platform-neutral and depends on the injected crypto provider.

const client = await createAuthrimClient({
  // ...
  dpop: {
    tokenRequests: true,
    algorithm: 'ES256',
  },
});

Property	Type	Default	Description
tokenRequests	boolean	false	Attach DPoP proofs to token endpoint requests such as authorization-code exchange
algorithm	'ES256' | 'PS256' | 'EdDSA'	'ES256'	DPoP proof signing algorithm

If tokenRequests is enabled, the configured CryptoProvider must also implement the DPoP extension methods described in Provider Interfaces.

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

Resolved default scopes for the client. Current authorization-code and PAR helpers accept a per-request scope string and default to 'openid profile' when no request scope is provided.

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

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)
hashOptions.hashLength	16
dpop.tokenRequests	false
dpop.algorithm	'ES256'

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: {
    hashLength: 22,
  },
  dpop: {
    tokenRequests: true,
    algorithm: 'ES256',
  },
  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