Authentication

The SDK authenticates every request to api.deepidv.com with an x-api-key header. This guide covers setup, security, and advanced configurations.

Need a key? Generate one from the API Authentication page. Keys are owned by a user in your organization and carry that user’s permissions.

Basic setup

apiKey is the only required configuration field:

import { DeepIDV } from '@deepidv/server';

const client = new DeepIDV({
  apiKey: process.env.DEEPIDV_API_KEY!,
});

Every HTTP request then automatically includes:

x-api-key: your-api-key-here
Accept: application/json

Security best practices

Use environment variables

Never hardcode API keys in source control:

// Bad — key committed to source
const client = new DeepIDV({ apiKey: 'sk_live_abc123...' });

// Good — key from the environment
const client = new DeepIDV({ apiKey: process.env.DEEPIDV_API_KEY! });

Never log the full key

The SDK automatically redacts API keys in error output. If you need to log which key was used, log the redacted form from AuthenticationError:

import { AuthenticationError } from '@deepidv/server';

try {
  await client.document.scan({ image });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Safe to log — only the last 4 characters are shown
    console.error(`Auth failed with key: ${err.redactedKey}`);
    // → "Auth failed with key: ****abcd"
  }
}

Rotate keys

If a key is compromised:

Generate a new API key in the deepidv dashboard.
Update your environment variable.
Revoke the old key.

No code changes are needed — the key is externalized.

Use a key per environment

# .env.development
DEEPIDV_API_KEY=sk_test_dev_...

# .env.production
DEEPIDV_API_KEY=sk_live_prod_...

API key redaction

When an AuthenticationError is thrown, the SDK stores only a redacted version of the key. When serialized with JSON.stringify(), the full key is never included:

JSON.stringify(authError);
// {
//   "type": "AuthenticationError",
//   "message": "Invalid API key",
//   "status": 401,
//   "redactedKey": "****abcd"
// }

This makes it safe to forward SDK errors to Sentry, Datadog, or any error-tracking service. See Error Handling for the full error model.

Custom fetch for proxy / mTLS

To route requests through a proxy or attach mutual-TLS certificates, provide a custom fetch implementation:

import { DeepIDV } from '@deepidv/server';
import { ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('https://proxy.internal:8080');

const client = new DeepIDV({
  apiKey: process.env.DEEPIDV_API_KEY!,
  fetch: (url, init) => fetch(url, { ...init, dispatcher }),
});

Cloudflare Workers service binding

const client = new DeepIDV({
  apiKey: env.DEEPIDV_API_KEY,
  fetch: env.DEEPIDV_SERVICE.fetch.bind(env.DEEPIDV_SERVICE),
});

See Configuration for more fetch injection patterns.

Validation

The SDK validates the API key synchronously at construction time, before any network call:

// Throws ValidationError — apiKey cannot be empty
new DeepIDV({ apiKey: '' });

// Throws ValidationError — apiKey is required
new DeepIDV({} as any);

This surfaces configuration mistakes immediately rather than on the first request.

Guides

TypeScript

Basic setup

Security best practices

Use environment variables

Never log the full key

Rotate keys

Use a key per environment

API key redaction

Custom fetch for proxy / mTLS

Cloudflare Workers service binding

Validation

​Basic setup

​Security best practices

​Use environment variables

​Never log the full key

​Rotate keys

​Use a key per environment

​API key redaction

​Custom fetch for proxy / mTLS

​Cloudflare Workers service binding

​Validation

Basic setup

Security best practices

Use environment variables

Never log the full key

Rotate keys

Use a key per environment

API key redaction

Custom fetch for proxy / mTLS

Cloudflare Workers service binding

Validation