> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blursec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

# Configuration

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

```ts theme={null}
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>`.

```ts theme={null}
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

```ts theme={null}
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](/docs/resources/credentials)). 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

```ts theme={null}
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](https://github.com/blur-sec/blursec-sdk/blob/main/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.

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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
```