Configuring the SDK and REST API

To execute actions on server session provisioned wallets directly from your server, you can use Privy’s NodeJS Server SDK or by making requests to Privy’s REST API directly. Follow the instructions below to configure your desired integration.

If your server is a NodeJS environment, you can integrate the @privy-io/server-auth library to use server session provisioned actions.

To use @privy-io/server-auth, first install the library:

npm install @privy-io/server-auth@latest

Then, import the PrivyClient class and create an instance of it. As parameters to the PrivyClient’s constructor, pass your Privy app ID and app secret as a string.

import { PrivyClient } from '@privy-io/server-auth';

...

const privy = new PrivyClient('insert-your-app-id', 'insert-your-app-secret', {
  walletApi: {
    authorizationPrivateKey: 'wallet-auth:insert-your-authorization-key-from-the-dashboard'
  }
});

If you have enabled an authorization key for your wallets in the Dashboard, pass the key to the constructor as illustrated above.

When an authorization private key is provided, the Privy client will automatically sign all requests with this key and include the signature as the required privy-authorization-signature header in API calls, ensuring your server-side wallet actions are properly authenticated.

If your server is a NodeJS environment, you can integrate the @privy-io/server-auth library to use server session provisioned actions.

To use @privy-io/server-auth, first install the library:

npm install @privy-io/server-auth@latest

Then, import the PrivyClient class and create an instance of it. As parameters to the PrivyClient’s constructor, pass your Privy app ID and app secret as a string.

import { PrivyClient } from '@privy-io/server-auth';

...

const privy = new PrivyClient('insert-your-app-id', 'insert-your-app-secret', {
  walletApi: {
    authorizationPrivateKey: 'wallet-auth:insert-your-authorization-key-from-the-dashboard'
  }
});

If you have enabled an authorization key for your wallets in the Dashboard, pass the key to the constructor as illustrated above.

Using the REST API

You can also use Privy’s REST API directly to take actions with server session provisioned wallets. When requesting the REST API directly, you must set certain headers on your requests and manually sign payloads with your authorization private key. This involves three steps at a high-level:

Headers

Authorization

Include a basic auth Authorization header with your Privy app ID as the username and your app secret as the password. The header is the base64-encoding of <privy-app-id>:<privy-app-secret>.

This header is required on all requests.

privy-app-id

Include a privy-app-id header with your Privy app ID.

This header is required on all requests.

Authorization signature

If your app has registered authorization keys, when creating, modifying, or using wallets, you must sign your requests with your authorization key.

If your app does not have a authorization key enabled, authorization signatures are not required.

Follow the guide below to set up your environment to execute actions with wallets from your server.

Generate JSON payload

Generate a JSON payload containing the following fields. All fields are required unless otherwise specified.

version

required

Authorization signature version. Currently, 1 is the only version.

method

'POST'

required

HTTP method for the request. Currently, only 'POST' requests are used.

url

string

required

The full URL for the request. Should not include a trailing slash.

body

JSON

required

JSON body for the request.

headers

JSON

required

JSON object containing any Privy-specific headers, e.g. those that are prefixed with 'privy-'. This should not include any other headers, such as authentication headers, content-type, or trace headers.

headers['privy-app-id']

string

required

Privy app ID header (required).

Canonicalize the payload

Canonicalize the payload per RFC8785 and serialize it to a string. This GitHub repository links to various libraries for JSON canonicalization in different languages.

Sign the payload

Sign the serialized JSON with ECDSA P-256 using your app’s private key and serialize it to a base64-encoded string.

See the code snippets below to serialize and sign requests with your app’s private key.

import canonicalize from 'canonicalize'; // Support JSON canonicalization
import crypto from 'crypto'; // Support P-256 signing

// Replace this with your private key from the Dashboard
const PRIVY_AUTHORIZATION_KEY = 'wallet-auth:insert-your-private-key-here';
...

function getAuthorizationSignature({url, body}: {url: string; body: object}) {
  const payload = {
    version: 1,
    method: 'POST',
    url,
    body,
    headers: {
      'privy-app-id': 'insert-your-app-id'
    }
  };

  // JSON-canonicalize the payload and convert it to a buffer
  const serializedPayload = canonicalize(payload) as string;
  const serializedPayloadBuffer = Buffer.from(serializedPayload);

  // Replace this with your app's authorization key. We remove the 'wallet-auth:' prefix
  // from the key before using it to sign requests
  const privateKeyAsString = PRIVY_AUTHORIZATION_KEY.replace('wallet-auth:', '');

  // Convert your private key to PEM format, and instantiate a node crypto KeyObject for it
  const privateKeyAsPem = `-----BEGIN PRIVATE KEY-----\n${privateKeyAsString}\n-----END PRIVATE KEY-----`;
  const privateKey = crypto.createPrivateKey({
    key: privateKeyAsPem,
    format: 'pem',
  });

  // Sign the payload buffer with your private key and serialize the signature to a base64 string
  const signatureBuffer = crypto.sign('sha256', serializedPayloadBuffer, privateKey);
  const signature = signatureBuffer.toString('base64');
  return signature;
}

const authorizationSignature = getAuthorizationSignature({
  url: 'https://api.privy.io/v1/wallets/rpc',
  // Replace with your desired body
  body: {
    address: '0xb8B849D7647937eB7331Dc7b6C445651A3EC55aE',
    chain_type: 'ethereum',
    method: 'personal_sign',
    params: {
      message: 'Hello, Ethereum',
      encoding: 'utf-8'
    }
  },
});

import canonicalize from 'canonicalize'; // Support JSON canonicalization
import crypto from 'crypto'; // Support P-256 signing

// Replace this with your private key from the Dashboard
const PRIVY_AUTHORIZATION_KEY = 'wallet-auth:insert-your-private-key-here';
...

function getAuthorizationSignature({url, body}: {url: string; body: object}) {
  const payload = {
    version: 1,
    method: 'POST',
    url,
    body,
    headers: {
      'privy-app-id': 'insert-your-app-id'
    }
  };

  // JSON-canonicalize the payload and convert it to a buffer
  const serializedPayload = canonicalize(payload) as string;
  const serializedPayloadBuffer = Buffer.from(serializedPayload);

  // Replace this with your app's authorization key. We remove the 'wallet-auth:' prefix
  // from the key before using it to sign requests
  const privateKeyAsString = PRIVY_AUTHORIZATION_KEY.replace('wallet-auth:', '');

  // Convert your private key to PEM format, and instantiate a node crypto KeyObject for it
  const privateKeyAsPem = `-----BEGIN PRIVATE KEY-----\n${privateKeyAsString}\n-----END PRIVATE KEY-----`;
  const privateKey = crypto.createPrivateKey({
    key: privateKeyAsPem,
    format: 'pem',
  });

  // Sign the payload buffer with your private key and serialize the signature to a base64 string
  const signatureBuffer = crypto.sign('sha256', serializedPayloadBuffer, privateKey);
  const signature = signatureBuffer.toString('base64');
  return signature;
}

const authorizationSignature = getAuthorizationSignature({
  url: 'https://api.privy.io/v1/wallets/rpc',
  // Replace with your desired body
  body: {
    address: '0xb8B849D7647937eB7331Dc7b6C445651A3EC55aE',
    chain_type: 'ethereum',
    method: 'personal_sign',
    params: {
      message: 'Hello, Ethereum',
      encoding: 'utf-8'
    }
  },
});

Embedded wallets

Using embedded wallets

Funding

Gas and asset management

Server sessions

Global wallets

Advanced Topics

Configuring the SDK and REST API

Using the REST API

Headers

Authorization signature

Embedded wallets

Using embedded wallets

Funding

Gas and asset management

Server sessions

Global wallets

Advanced Topics

​Using the REST API

​Headers

​Authorization signature

Using the REST API

Headers

Authorization signature