Migrating from server-auth

Overview

If your app previously used Privy’s @privy-io/server-auth SDK, follow the migration guide below to upgrade to the @privy-io/node package. The new @privy-io/node package is a major upgrade from the @privy-io/server-auth package, with an improved structure, error handling, and better support for the latest features available in Privy’s API.

Initialization

0. System requirements

The new @privy-io/node package, like its predecessor, is compatible with multiple server-side JavaScript runtimes. Specifically, the following runtime versions are supported:

Node.js 20 LTS or later (non-EOL) versions.
Deno v1.28.0 or higher.
Bun 1.0 or later.
Cloudflare Workers.
Vercel Edge Runtime.
Nitro v2.6 or greater.

Refer to the package’s README for the most up-to-date list of supported runtimes.

1. Privy client initialization

The PrivyClient class now takes in a single configuration object, instead of positional appId and appSecret parameters.

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

const privy = new PrivyClient('insert-your-app-id', 'insert-your-app-secret'); 
const newPrivy = new NewPrivyClient({ 
  appId: 'insert-your-app-id', 
  appSecret: 'insert-your-app-secret'
}); 

This results in a more consistent API as other configuration options are set.

2. Working with resources

The new package splits different groups of methods into resource-specific interfaces. Whereas before you could call methods directly on the PrivyClient instance, you now generally need to call methods on the resource-specific interfaces.

The new SDK offers a one-to-one mapping of the API endpoints described in the API reference. To facilitate this, methods called on the PrivyClient instance that need parameters to be passed in now take those in snake_case instead of camelCase, matching the API format exactly.

For example, for creating or importing a user with the @privy-io/node package, you will use the users() interface:

import {AuthorizationContext, PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({appId: 'insert-your-app-id', appSecret: 'insert-your-app-secret'});

const user = await privy.importUser({ 
  linkedAccounts: [{type: 'email', address: '[email protected]'}], 
  wallets: [{chainType: 'ethereum'}] 
}); 
const user = await privy.users().create({ 
  linked_accounts: [{type: 'email', address: '[email protected]'}], 
  wallets: [{chain_type: 'ethereum'}] 
});

Likewise, many of the methods that were previously under the walletApi interface are now under the wallets() or ` interface.

In `@privy-io/server-auth`	In `@privy-io/node`
`privy.walletApi.createWallet`	`privy.wallets().create`
`privy.walletApi.rpc`	`privy.wallets().rpc`
`privy.walletApi.ethereum.signMessage`	`privy.wallets().ethereum().signMessage`
`privy.walletApi.createPolicy`	`privy.policies().create`

3. Authorization signatures

The new package introduces the AuthorizationContext interface, which simplifies the process of generating authorization signatures.

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

const privy = new PrivyClient('insert-your-app-id', 'insert-your-app-secret'); 

privy.walletApi.updateAuthorizationKey('insert-your-authorization-private-key'); 
const authorizationContext: AuthorizationContext = { 
  authorization_private_keys: ['insert-your-authorization-private-key'] 
}; 

Unlike before, where you would need to manually set an authorization key at the level of the client, you will now pass the authorization context as a parameter to the method you are calling, giving you fine grained control over the authorization context for each call, allowing you to use different keys or quorums for each request. Further, the new interface support combining different signing mechanisms in the authorization context as you see fit, for example, by combining a user JWT and an authorization key for a resource that is owned by both a user and a service:

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

const privy = new PrivyClient('insert-your-app-id', 'insert-your-app-secret'); 

const {authorizationKey} = await privy.walletApi.generateUserSigner({ 
  userJwt: 'insert-user-jwt'
}); 
privy.walletApi.updateAuthorizationKey(authorizationKey); 
const authorizationContext: AuthorizationContext = { 
  user_jwts: ['insert-user-jwt'], 
  authorization_private_keys: ['insert-authorization-private-key'] 
}; 

Check out the Authorization Context guide in full for more details on the new interface.

The privy.walletApi.generateUserSigner method is no longer available in the @privy-io/node package. Instead you can set the user_jwts property on the authorization context, and the SDK will handle the authorization keys automatically.

4. Proper error handling

In @privy-io/server-auth, some APIs returned null when a resource was not found. In @privy-io/node, if the API returns a 404 not found response, the SDK throws a NotFoundError. For example, the getUserByEmail method in @privy-io/server-auth returned null when no matching user existed. In @privy-io/node, users().getByEmailAddress throws a NotFoundError instead. If your app relies on checking whether a resource exists, catch NotFoundError and handle it as a missing resource:

import {NotFoundError, PrivyClient, type User} from '@privy-io/node';

const privy = new PrivyClient({appId: 'insert-your-app-id', appSecret: 'insert-your-app-secret'});

let user: User | null = null;

try {
  user = await privy.users().getByEmailAddress({address: '[email protected]'});
} catch (error) {
  if (error instanceof NotFoundError) {
    user = null;
  } else {
    throw error;
  }
}

if (user) {
  // Handle the matching user.
}

Get started

Client-side SDKs

Server-side SDKs

REST API

Changelogs

Troubleshooting and tips

Migrating from server-auth

Overview

Initialization

0. System requirements

1. Privy client initialization

2. Working with resources

3. Authorization signatures

4. Proper error handling

​Overview

​Initialization

​0. System requirements

​1. Privy client initialization

​2. Working with resources

​3. Authorization signatures

​4. Proper error handling

Overview

Initialization

0. System requirements

1. Privy client initialization

2. Working with resources

3. Authorization signatures

4. Proper error handling