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

# TypeScript server

> Use @0xkey-io/sdk-server for API key–signed requests, Express/Next.js proxies, and server-side auth helpers.

## Overview

[`@0xkey-io/sdk-server`](https://www.npmjs.com/package/@0xkey-io/sdk-server) signs requests to the 0xkey API with your organization's API keypair. Use it for:

* Backend automation (wallets, policies, users)
* Proxies that sign specific user-initiated activities with the **parent org** key (sub-org creation, email auth, OTP)
* Next.js Server Actions exported as `server.*` helpers

The package also re-exports [`@0xkey-io/http`](https://www.npmjs.com/package/@0xkey-io/http) for lower-level typed requests.

<Note>
  **Company Wallets** and **delegated access** backends typically use this package (or the [Go SDK](/sdks/go/getting-started)). **Embedded Wallets** in React should still use [React Wallet Kit](/sdks/react/getting-started) on the client; use `sdk-server` only where you need a trusted backend.
</Note>

***

## Installation

<CodeGroup>
  ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npm install @0xkey-io/sdk-server
  ```

  ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  pnpm add @0xkey-io/sdk-server
  ```

  ```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark"}}
  yarn add @0xkey-io/sdk-server
  ```
</CodeGroup>

***

## Initializing

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { ZeroXKey } from "@0xkey-io/sdk-server";

const zeroXKey = new ZeroXKey({
  defaultOrganizationId: process.env.OXKEY_ORGANIZATION_ID!,
  apiBaseUrl: process.env.OXKEY_API_BASE_URL ?? "https://api.0xkey.io",
  apiPrivateKey: process.env.OXKEY_API_PRIVATE_KEY!,
  apiPublicKey: process.env.OXKEY_API_PUBLIC_KEY!,
});
```

<ParamField body="defaultOrganizationId" type="string" required>
  Root organization ID for requests unless overridden per call.
</ParamField>

<ParamField body="apiBaseUrl" type="string" required>
  Public API base URL. Use `https://api.0xkey.com` with local-gateway during dev.
</ParamField>

<ParamField body="apiPrivateKey" type="string" required>
  API private key (never expose to the browser).
</ParamField>

<ParamField body="apiPublicKey" type="string" required>
  API public key registered in the Dashboard for the private key above.
</ParamField>

***

## Creating clients

API calls must be [stamped](/developer-reference/api-overview/stamps). With the server SDK, stamping uses your API keypair.

### `apiClient()`

Returns a typed client that signs every request with the configured API credentials.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const api = zeroXKey.apiClient();
const whoami = await api.getWhoami({ organizationId: process.env.OXKEY_ORGANIZATION_ID! });
```

Create wallets with helper constants:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { DEFAULT_ETHEREUM_ACCOUNTS } from "@0xkey-io/sdk-server";

const { walletId, addresses } = await api.createWallet({
  walletName: "Treasury",
  accounts: DEFAULT_ETHEREUM_ACCOUNTS,
});
```

Runnable sample: [`examples/with-sdk-server`](https://github.com/0xkey-io/sdk-js/tree/main/examples/with-sdk-server).

***

## API proxies

Some user flows must be signed by the **parent organization** (for example `createSubOrganization`, `emailAuth`, `initOtp`). You can implement routes yourself with `apiClient()`, or use built-in proxy handlers.

Default allowed proxy methods:

`oauth`, `createReadWriteSession`, `createSubOrganization`, `emailAuth`, `initUserEmailRecovery`

### Express

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import express from "express";
import { ZeroXKey } from "@0xkey-io/sdk-server";

const app = express();
app.use(express.json());

const zeroXKey = new ZeroXKey({ /* ... */ });

const proxy = zeroXKey.expressProxyHandler({
  allowedMethods: ["createSubOrganization", "emailAuth", "getSubOrgIds"],
});

app.post("/api/proxy", proxy);
```

### Next.js Pages Router

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
// pages/api/proxy.ts
import { ZeroXKey } from "@0xkey-io/sdk-server";

const zeroXKey = new ZeroXKey({ /* ... */ });

export default zeroXKey.nextProxyHandler({
  allowedMethods: ["createSubOrganization", "emailAuth", "getSubOrgIds"],
});
```

Restrict `allowedMethods` to the smallest set your frontend needs.

***

## Server Actions (`server.*`)

The package exports helpers for common auth flows (usable from Next.js `"use server"` modules or your own backend):

| Helper                                            | Purpose                                   |
| :------------------------------------------------ | :---------------------------------------- |
| `server.sendOtp`                                  | Start email or SMS OTP                    |
| `server.verifyOtp`                                | Verify OTP code                           |
| `server.otpLogin`                                 | Complete OTP login with client public key |
| `server.oauthLogin`                               | Complete OAuth with OIDC token            |
| `server.sendCredential`                           | Email magic-link / credential delivery    |
| `server.createSuborg`                             | Create sub-organization                   |
| `server.getOrCreateSuborg`                        | Idempotent sub-org lookup / create        |
| `server.getSuborgs` / `server.getVerifiedSuborgs` | List sub-orgs by filter                   |
| `server.getUsers`                                 | List users in an organization             |
| `server.createOauthProviders`                     | Register OAuth provider metadata          |

Example OTP initiation:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { server } from "@0xkey-io/sdk-server";

const init = await server.sendOtp({
  contact: "user@example.com",
  otpType: "OTP_TYPE_EMAIL",
  appName: "My App",
  userIdentifier: clientPublicKey,
  otpLength: 6,
});

if (init?.otpId) {
  // prompt user for code, then server.verifyOtp / server.otpLogin
}
```

Pair with `@0xkey-io/core` or `@0xkey-io/react-wallet-kit` on the client for session stamping. See [Email authentication](/authentication/email) and [Backend setup](/authentication/backend-setup).

***

## Related packages

| Package                                                                                | When to use                                   |
| :------------------------------------------------------------------------------------- | :-------------------------------------------- |
| [`@0xkey-io/core`](/sdks/typescript-frontend/getting-started)                          | Browser / custom UI clients                   |
| [`@0xkey-io/http`](https://www.npmjs.com/package/@0xkey-io/http)                       | Manual stamping without the `ZeroXKey` facade |
| [`@0xkey-io/api-key-stamper`](https://www.npmjs.com/package/@0xkey-io/api-key-stamper) | Standalone P-256 request stamps               |
| [Go SDK](/sdks/go/getting-started)                                                     | Non-Node backends                             |

***

## Examples

| Example                                                                                      | Description                    |
| :------------------------------------------------------------------------------------------- | :----------------------------- |
| [`with-sdk-server`](https://github.com/0xkey-io/sdk-js/tree/main/examples/with-sdk-server)   | Minimal Whoami via API key     |
| [`delegated-access`](https://github.com/0xkey-io/sdk-js/tree/main/examples/delegated-access) | Scoped backend signing         |
| [`otp-auth`](https://github.com/0xkey-io/sdk-js/tree/main/examples/otp-auth)                 | Email OTP with/without backend |
| [`oauth`](https://github.com/0xkey-io/sdk-js/tree/main/examples/oauth)                       | OAuth login flow               |