Configuration
Construct the Tawa client and understand region resolution and custom base URLs.
Construct the client
import { TawaGuard } from "@tawaguard/sdk";
const tawa = await TawaGuard.create(process.env.TAWA_API_KEY!);TawaGuard.create authenticates against /verify before returning, so a bad
key surfaces at construction time rather than on the first scan call. Once
authenticated, the client resolves your organization's region and talks
directly to that region's gateway for every call after that — the
control plane is only touched once.
Options
Prop
Type
const tawa = await TawaGuard.create(apiKey, {
baseUrl: "https://tawa.internal.acme.com/v1", // override the default
});Custom base URL
Passing baseUrl explicitly always wins and disables the automatic region
resolution described above — every call goes to exactly the URL you gave it.
const tawa = await TawaGuard.create(apiKey, {
baseUrl: "https://gateway.preview.tawaguard.com/v1",
});TawaGuard.create always calls ${baseUrl}/verify first, with no exception
for a custom baseUrl — whatever you point it at must implement that route
itself. The example above works because it points at a locally-running
tawa-js-front, which does. Pointing baseUrl directly at a bare
tawa-gateway or Tawa Guard worker instance does not currently work —
neither implements /verify, so construction fails immediately with a 404
before any scan call is attempted. If you're standing up a private/on-prem
deployment, your endpoint needs to implement /verify (it can be a stub
that always returns { valid: true } if you're not reusing better-auth's
API-key model) until this gap is closed.
Error handling
All API and network errors throw a FetchError:
import { TawaGuard, FetchError } from "@tawaguard/sdk";
try {
const tawa = await TawaGuard.create(apiKey);
const result = await tawa.analyze("user input");
} catch (err) {
if (err instanceof FetchError) {
console.error(err.message); // error description
console.error(err.status); // HTTP status code (or null for network errors)
console.error(err.retryable); // whether a retry could succeed
}
}The client retries transient failures (HTTP 429 and 5xx) automatically,
up to 3 attempts with exponential backoff.