@turnkey/api-key-stamper

Sign Turnkey requests with an API key pair

@turnkey/api-key-stamper stamps Turnkey API requests using a P-256 API key pair. It is intended for server-side or CLI environments where the key pair is stored securely in environment variables or a secrets manager.

Never use ApiKeyStamper in a browser environment. API private keys would be exposed to the client. Use WebauthnStamper or IframeStamper for browser-based authentication instead.

Installation

npm

npm install @turnkey/api-key-stamper @turnkey/http

Usage

import { ApiKeyStamper } from "@turnkey/api-key-stamper";
import { TurnkeyClient } from "@turnkey/http";

const stamper = new ApiKeyStamper({
  apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY!,
  apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY!,
});

const client = new TurnkeyClient(
  { baseUrl: "https://api.turnkey.com" },
  stamper,
);

Once you have a TurnkeyClient, call any API method and the stamper signs the request automatically:

const whoami = await client.getWhoami({
  organizationId: process.env.TURNKEY_ORGANIZATION_ID!,
});

console.log(whoami.organizationId, whoami.userId);

ApiKeyStamper constructor

apiPublicKey · string · required

The hex-encoded P-256 public key from your Turnkey API key pair. Included in every stamp so Turnkey can identify which authenticator signed the request.

apiPrivateKey · string · required

The hex-encoded P-256 private key used to sign request payloads. Keep this value in a secure secrets store and never commit it to source control.

runtimeOverride · 'browser' | 'node' | 'purejs'

Override the automatic runtime detection. By default the stamper detects whether it is running in a browser (Web Crypto API), Node.js (node:crypto), or a pure-JS fallback for environments without native crypto (e.g., older React Native). Only set this if the automatic detection produces the wrong result.

signWithApiKey function

If you need a raw signature rather than a full HTTP stamp, the package also exports signWithApiKey directly:

import { signWithApiKey, SignatureFormat } from "@turnkey/api-key-stamper";

// Returns a DER-encoded hex signature by default
const derSignature = await signWithApiKey({
  content: "message to sign",
  publicKey: process.env.TURNKEY_API_PUBLIC_KEY!,
  privateKey: process.env.TURNKEY_API_PRIVATE_KEY!,
});

You can also call stamper.sign(payload, format) to get either a DER or raw signature:

import { ApiKeyStamper, SignatureFormat } from "@turnkey/api-key-stamper";

const stamper = new ApiKeyStamper({ apiPublicKey: "...", apiPrivateKey: "..." });

// Raw (r || s) hex-encoded signature
const rawSignature = await stamper.sign(payload, SignatureFormat.Raw);

// DER-encoded hex signature
const derSignature = await stamper.sign(payload, SignatureFormat.Der);

Runtime detection

The stamper automatically selects the signing backend based on the JavaScript environment:

Runtime	Signing backend
Browser with Web Crypto (window.crypto.subtle)	webcrypto
Node.js (process.versions.node)	nodecrypto
Fallback (old browsers, React Native)	Pure-JS P-256 implementation

Generating API keys

Create an API key pair from the Turnkey dashboard:

1. Open the Turnkey dashboard

   Go to app.turnkey.com and sign in.

2. Navigate to API keys

   Select your organization, then go to Settings > API keys.

3. Create a new API key

   Click Create API key, give it a name, and copy both the public and private key values. The private key is shown only once.

4. Store the keys securely

   Add the keys to your environment:

   TURNKEY_API_PUBLIC_KEY=your-public-key
   TURNKEY_API_PRIVATE_KEY=your-private-key