TypeScript server

Overview

@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 for lower-level typed requests.

Company Wallets and delegated access backends typically use this package (or the Go SDK). Embedded Wallets in React should still use React Wallet Kit on the client; use sdk-server only where you need a trusted backend.

Installation

npm install @0xkey-io/sdk-server

pnpm add @0xkey-io/sdk-server

yarn add @0xkey-io/sdk-server

Initializing

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!,
});

defaultOrganizationId

string

required

Root organization ID for requests unless overridden per call.

apiBaseUrl

string

required

Public API base URL. Use https://api.0xkey.com with local-gateway during dev.

apiPrivateKey

string

required

API private key (never expose to the browser).

apiPublicKey

string

required

API public key registered in the Dashboard for the private key above.

Creating clients

API calls must be stamped. With the server SDK, stamping uses your API keypair.

`apiClient()`

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

const api = zeroXKey.apiClient();
const whoami = await api.getWhoami({ organizationId: process.env.OXKEY_ORGANIZATION_ID! });

Create wallets with helper constants:

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.

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

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

// 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:

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 and Backend setup.

Package	When to use
`@0xkey-io/core`	Browser / custom UI clients
`@0xkey-io/http`	Manual stamping without the `ZeroXKey` facade
`@0xkey-io/api-key-stamper`	Standalone P-256 request stamps
Go SDK	Non-Node backends

Examples

Example	Description
`with-sdk-server`	Minimal Whoami via API key
`delegated-access`	Scoped backend signing
`otp-auth`	Email OTP with/without backend
`oauth`	OAuth login flow

​Overview

​Installation

​Initializing

​Creating clients

​apiClient()

​API proxies

​Express

​Next.js Pages Router

​Server Actions (server.*)

​Related packages

​Examples

Overview

Installation

Initializing

Creating clients

`apiClient()`

API proxies

Express

Next.js Pages Router

Server Actions (`server.*`)

Related packages

Examples