Skip to main content

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.

​
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

​
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):
HelperPurpose
server.sendOtpStart email or SMS OTP
server.verifyOtpVerify OTP code
server.otpLoginComplete OTP login with client public key
server.oauthLoginComplete OAuth with OIDC token
server.sendCredentialEmail magic-link / credential delivery
server.createSuborgCreate sub-organization
server.getOrCreateSuborgIdempotent sub-org lookup / create
server.getSuborgs / server.getVerifiedSuborgsList sub-orgs by filter
server.getUsersList users in an organization
server.createOauthProvidersRegister 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.
PackageWhen to use
@0xkey-io/coreBrowser / custom UI clients
@0xkey-io/httpManual stamping without the ZeroXKey facade
@0xkey-io/api-key-stamperStandalone P-256 request stamps
Go SDKNon-Node backends

​
Examples

ExampleDescription
with-sdk-serverMinimal Whoami via API key
delegated-accessScoped backend signing
otp-authEmail OTP with/without backend
oauthOAuth login flow