SDK Authentication

The Taildove TypeScript SDK authenticates every request with a Taildove API key.

When you create a client, the SDK stores your key and sends it as:

Authorization: Bearer hz_<your-key>

Basic setup

import { createTaildoveClient } from "../lib/taildove-sdk";

const taildove = createTaildoveClient({
  apiKey: process.env.TAILDOVE_API_KEY!,
});

Rotate or replace the API key

If you need to replace the API key at runtime, use setApiKey():

taildove.setApiKey(process.env.TAILDOVE_API_KEY_ROTATED!);

Access the auth headers

If you need the raw authentication headers for adjacent custom requests, use getAuthHeaders():

const headers = {
  ...taildove.getAuthHeaders(),
  "Content-Type": "application/json",
};

Custom base URL

Use baseUrl when pointing the SDK at a different environment:

const taildove = createTaildoveClient({
  apiKey: process.env.TAILDOVE_API_KEY!,
  baseUrl: "http://localhost:3000/api/v1",
});

Best practices

• Store API keys in environment variables, not in client-side source files
• Use separate keys for production, staging, and local development
• Revoke keys immediately if they are exposed
• Prefer short-lived or regularly rotated keys for automation

Error handling

If authentication fails, the SDK throws TaildoveApiError with the API status code and payload.

import { TaildoveApiError } from "../lib/taildove-sdk";

try {
  await taildove.contacts.list();
} catch (error) {
  if (error instanceof TaildoveApiError && error.status === 401) {
    console.error("Invalid or expired Taildove API key");
  }
}

To create or revoke keys, see API Keys.