---
title: Verify configuration
description: Configuration options, defaults, valid ranges, and error handling for @orbitrail/verify.
url: https://pr-1-3b5c652a9824.thally.app/verify-configuration
---

# Verify configuration

Configuration options, defaults, valid ranges, and error handling for @orbitrail/verify.

Every option for `createVerifyClient` is validated at construction time. Out-of-range or non-integer values throw a `RangeError` immediately, so configuration mistakes surface before any payload is processed.

## Options reference

| Option | Type | Default | Min | Max | Description |
|---|---|---|---|---|---|
| `apiKey` | `string` | _(required)_ | — | — | Your OrbitRail API key |
| `flushLimit` | `number` | `100` | `1` | `1,000` | Maximum number of verifications buffered before an automatic flush |
| `algorithm` | `string` | `"hmac-sha256"` | — | — | Signature algorithm: `"hmac-sha256"` or `"ed25519"` |
| `clockToleranceSeconds` | `number` | `60` | `0` | `300` | Allowed clock skew when validating signed timestamps |
| `maxSignatureAgeSeconds` | `number` | `300` | `1` | `3,600` | Maximum age of a signature before it is rejected |
| `replayCacheSeconds` | `number` | `600` | `60` | `3,600` | Duration that verified payload identifiers are cached to prevent replay |

## Defaults

Create a client with only the required `apiKey` to use every default:

```typescript
import { createVerifyClient } from "@orbitrail/verify";

const client = createVerifyClient({ apiKey: "my-key" });

client.flushLimit;            // 100
client.algorithm;             // "hmac-sha256"
client.clockToleranceSeconds; // 60
client.maxSignatureAgeSeconds; // 300
client.replayCacheSeconds;    // 600
```

## Customizing options

Override any combination of optional fields:

```typescript
const client = createVerifyClient({
  apiKey: "my-key",
  algorithm: "ed25519",
  flushLimit: 250,
  clockToleranceSeconds: 120,
  maxSignatureAgeSeconds: 900,
  replayCacheSeconds: 900,
});
```

## Validation errors

Every numeric option must be an integer within its documented range. The factory throws a `RangeError` if any value is out of bounds or not an integer:

```typescript
// flushLimit must be an integer from 1 to 1000
createVerifyClient({ apiKey: "k", flushLimit: 0 });
// RangeError: flushLimit must be an integer from 1 to 1000

// clockToleranceSeconds must be an integer from 0 to 300
createVerifyClient({ apiKey: "k", clockToleranceSeconds: 301 });
// RangeError: clockToleranceSeconds must be an integer from 0 to 300

// maxSignatureAgeSeconds must be an integer from 1 to 3600
createVerifyClient({ apiKey: "k", maxSignatureAgeSeconds: 3601 });
// RangeError: maxSignatureAgeSeconds must be an integer from 1 to 3600

// replayCacheSeconds must be an integer from 60 to 3600
createVerifyClient({ apiKey: "k", replayCacheSeconds: 59 });
// RangeError: replayCacheSeconds must be an integer from 60 to 3600
```

## Algorithm selection

OrbitRail Verify supports two signature algorithms:

| Algorithm | Value | Description |
|---|---|---|
| HMAC-SHA256 | `"hmac-sha256"` | Symmetric key verification (default) |
| Ed25519 | `"ed25519"` | Asymmetric key verification |

```typescript
// HMAC-SHA256 (default)
const hmacClient = createVerifyClient({ apiKey: "my-key" });

// Ed25519
const edClient = createVerifyClient({
  apiKey: "my-key",
  algorithm: "ed25519",
});
```