# Node SDK

Node.js 20 or later.

## Install

```sh
npm install @ohauthcat/node
```

## Configure

`new OhAuthCat(options)` takes `apiKey` (the secret key, `sk_...`) and, for sign-in, `clientId` (the publishable key, `pk_...`) and `environmentId` (`env_...`). Optional: `timeoutMs`, `maxRetries`, and `apiBaseUrl` / `authBaseUrl` for any deployment other than production. Keep the client on your server.

## First call

Every API operation is a method on its resource, named after the operation: `await client.organizations.createOrganization({ body: { name: "Acme" } })`, or `await client.organizations.getOrganization({ path: { org: "org_..." } })`. `client.paginate("listOrganizations", {})` is an async iterator over every page.

SSO: `client.sso.getAuthorizationUrl({ redirectUri, state, organization })` returns `{ url, codeVerifier }`; keep the verifier on your server. On the callback, `await client.sso.getProfileAndToken(...)` exchanges the code once. The [Node quickstart](/get-started/quickstart-node/) shows the whole flow.

## Errors

Every API error is an `OhAuthCatError` with the stable `code`, `status`, `type`, `param`, `docUrl` and `requestId`; see the [error codes](/errors/). `PlanLimitReachedError` adds the `metric` a plan refused. `RestartSignIn` means the code exchange cannot be retried: start a fresh sign-in.

## Webhooks

`webhooks.verify(rawBody, header, [secret])` checks the `OhAuthCat-Signature` header against the exact raw body bytes and returns the event. Pass every secret you hold during a rotation. A refusal throws `WebhookVerificationError` whose `code` is, for example, `signature_invalid` or `timestamp_outside` (older than 300 seconds).

## Reference

Every method maps to an operation in the [API reference](/reference/api/); webhook payloads are in [webhook events](/reference/webhook-events/).
