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