Configuration

The Blursec (or BlursecClient) constructor accepts a single BlursecClientConfig object:

import { Blursec } from "@blursec/sdk";

const blursec = new Blursec({
  apiKey: process.env.BLURSEC_API_KEY!,    // required
  environment: "production",                // optional
  baseUrl: undefined,                       // optional
  timeoutMs: 30_000,                        // optional
  defaultHeaders: { "X-Tenant": "acme" },   // optional
  fetch: globalThis.fetch,                  // optional
});

The resolved config is exposed read-only on blursec.config for diagnostics.

`apiKey` — required

Non-empty string. Sent on every request as Authorization: Bearer <apiKey>.

new Blursec({ apiKey: "" }); // ⇒ throws BlursecValidationError

Never embed the key in client-side bundles. API keys grant full access to your Blursec workspace.

`environment` — default: `"production"`

One of "production", "staging", "local". Selects the default baseUrl:

environment	base URL
`production`	`https://api.blursec.com`
`staging`	`https://api.staging.blursec.com`
`local`	`http://localhost:8080`

`baseUrl` — default: derived from `environment`

Explicit override for the API base URL. Useful for:

Self-hosted Blursec deployments
Pointing the SDK at a recording proxy (e.g. for VCR-style tests)
Per-region traffic steering

new Blursec({
  apiKey: "...",
  baseUrl: "https://blursec.eu.acme.internal",
});

The SDK normalizes trailing slashes — https://api.example.com and https://api.example.com/ behave identically.

`timeoutMs` — default: `30_000`

Default per-request timeout in milliseconds. Applied to every request the SDK makes via AbortController, unless overridden by a per-call options.timeoutMs.

Credential checks use their own default of 1500 ms (see credentials.md). This config option only affects auth.* and sessions.* calls, plus arbitrary client.request() calls.

Must be a positive finite number — 0, -1, and Infinity throw BlursecValidationError.

`defaultHeaders` — default: `{}`

Extra headers attached to every outbound request. Useful for:

Tenant routing (X-Tenant, X-Workspace-Id)
Tracing (traceparent, X-Request-Id)
Feature flags

Per-call options.headers always wins over defaults. The SDK manages Authorization, Accept, and Content-Type itself.

`fetch` — default: `globalThis.fetch`

Inject a custom fetch implementation. Required on:

Runtimes without a global fetch (older Node, some embedded environments)
Tests where you want to record/replay HTTP traffic
Production setups with custom retry, telemetry, or DNS-pinning logic

import { Blursec } from "@blursec/sdk";
import { fetch as undiciFetch } from "undici";

new Blursec({
  apiKey: "...",
  fetch: undiciFetch,
});

Don’t add retries on credential checks. A failed checkCredential should fail open instantly — see examples/custom-fetch-retry.ts.

`logger` / `logLevel` — optional structured audit logging

Pass a BlursecLogger to receive PII-scrubbed, structured-log entries for every security-relevant event (client init, each check, fail-open, breaker transitions). Omitted → the SDK emits nothing.

import { Blursec, createConsoleLogger } from "@blursec/sdk";

const blursec = new Blursec({
  apiKey: process.env.BLURSEC_API_KEY!,
  logger: createConsoleLogger(),   // or your own { log(entry) } sink
  logLevel: "info",                 // "debug" | "info" | "warn" | "error"; default "info"
});

audit-level entries are always emitted regardless of logLevel (SOC 2 audit trail). Use createNoopLogger() to explicitly silence everything.

`circuitBreaker` — optional

Guards the credential-check hot path: after repeated failures the breaker opens and rejects requests fast (folded into the existing fail-open path) so login latency doesn’t balloon during a Blursec incident.

new Blursec({
  apiKey: "...",
  circuitBreaker: {
    failureThreshold: 5,    // consecutive failures before opening; default 5
    resetTimeoutMs: 30_000, // time before a half-open probe; default 30s
    // enabled: false,      // disable entirely
  },
});

Defaults to enabled. Inspect live state for a /health endpoint via the exported CircuitBreaker.

Inspecting the resolved config

const blursec = new Blursec({ apiKey: "k" });
console.log(blursec.config);
// {
//   apiKey: "k",
//   environment: "production",
//   baseUrl: "https://api.blursec.com",
//   timeoutMs: 30000,
//   defaultHeaders: {},
//   fetch: [Function: fetch],
// }

Object.isFrozen(blursec.config); // true

Getting started

Resources

Configuration

Configuration

`apiKey` — required

`environment` — default: `"production"`

`baseUrl` — default: derived from `environment`

`timeoutMs` — default: `30_000`

`defaultHeaders` — default: `{}`

`fetch` — default: `globalThis.fetch`

`logger` / `logLevel` — optional structured audit logging

`circuitBreaker` — optional

Inspecting the resolved config

​Configuration

​apiKey — required

​environment — default: "production"

​baseUrl — default: derived from environment

​timeoutMs — default: 30_000

​defaultHeaders — default: {}

​fetch — default: globalThis.fetch

​logger / logLevel — optional structured audit logging

​circuitBreaker — optional

​Inspecting the resolved config

Configuration

`apiKey` — required

`environment` — default: `"production"`

`baseUrl` — default: derived from `environment`

`timeoutMs` — default: `30_000`

`defaultHeaders` — default: `{}`

`fetch` — default: `globalThis.fetch`

`logger` / `logLevel` — optional structured audit logging

`circuitBreaker` — optional

Inspecting the resolved config