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

# SDK configuration

> Configure the TapAce client with a server API key, API origin, per-attempt timeout, retry limit, and optional fetch implementation for your integration.

Configure a TapAce client once and reuse it across requests in your server application. Each resource uses the same HTTP configuration.

```typescript theme={null}
import { TapAce } from "@tapace/node";

const apiKey = process.env.TAPACE_API_KEY;
if (!apiKey) throw new Error("Set TAPACE_API_KEY");

const tapace = new TapAce({
  apiKey,
  baseUrl: "https://api.tapace.lk",
  timeoutMs: 30_000,
  maxRetries: 3,
});
```

| Option | Default | Meaning |
| - | - | - |
| `apiKey` | Required | Server API key with a test or live prefix. |
| `baseUrl` | `https://api.tapace.lk` | API origin. SDK methods append their own `v1/...` paths. |
| `timeoutMs` | `30000` | Timeout for each attempt, including response consumption. |
| `maxRetries` | `3` | Additional attempts after the initial request. Set `0` to disable SDK retries. |
| `fetch` | Global `fetch` | Optional implementation with the same interface as Node's fetch. |

`maxRetries` must be a non-negative safe integer. `timeoutMs` must be between 1 and 2,147,483,647 milliseconds. Each attempt has its own timeout, including response-body consumption. A custom fetch must honor the provided abort signal.

Do not append `/v1` to `baseUrl`; resource methods already include that segment. Unlike the HTTP reference's base URL, this option expects the origin.

## Environment

`tapace.environment` and `tapace.mode` both return `"test"` or `"live"`, detected from the key prefix. They do not change the API origin or create isolated templates.

Use `tapace.me.retrieve()` to confirm the authenticated organization and environment before running a job. A correctly prefixed key can still be revoked or invalid. Keep clients for different organizations or environments separate, and never replace a shared client's credentials during a request.

Test passes are isolated from live passes, but templates, assets and event details are shared. Use a dedicated template for integration tests that change a design or event.

## Per-operation options

Mutating methods accept `{ idempotencyKey?: string }` as their final options argument. Methods with an optional parameters argument may need `{}` before options:

```typescript theme={null}
import { idempotencyKey } from "@tapace/node";

// Within an operation with saved templateId and deploymentJobId:
await tapace.deployments.create(templateId, {}, {
  idempotencyKey: idempotencyKey("deploy-template", deploymentJobId),
});
```

Here `templateId` and `deploymentJobId` are values supplied by your application. Timeout and retry settings are client-wide; the current per-operation options do not expose a timeout, cancellation signal or retry override.

## Custom fetch

Use a custom fetch for controlled transport integration or tests:

```typescript theme={null}
const customFetch: typeof fetch = (input, init) => fetch(input, init);
const client = new TapAce({ apiKey, fetch: customFetch });
```

Preserve the supplied signal and headers. Avoid logging authorization headers or complete request bodies containing holder details. See [Errors and retries](https://tapace.lk/docs/sdk/node/reliability.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.