Authenticated signers

TIP

Authenticated signers enable users to fully control self-custodial wallets. All Privy client-side SDKs enable fully user self-custodial wallets by default via authenticated signers.

Self-custodial Privy wallets are those owned by an authorization key that the user controls. For example, you can configure fully user self-custodial wallets:

• Using a user's authenticated signer as the authorization key
• Using a user's passkey as the authorization key

Authenticated signers are P-256 authorization keys that users control directly via an authentication method. Privy infrastructure manages issuing session-based authorization keys to users via the Privy authenticated signer service. This configuration results in cryptographically-enforced user custody of wallets.

You can learn more about the authenticated signer architecture here.

Authentication methods

Privy integrates directly with any OIDC or JWT-based authentication system and also offers dozens of login methods natively, including email, SMS, social login, passkeys, and more. The authenticated signer service ensures that if a user is logged in, they always have access to their wallet.

Client-side authenticated signers

All Privy client-side SDKs enable fully user self-custodial wallets by default via authenticated signers.

Client-side authenticated signers are session-based authorization keys available via Privy client SDKs, and issued on the user's device. These authorization keys are managed internally by the Privy SDK and are used to authenticate with Privy's wallet API. Authenticated signers are only accessible when the user is authenticated.

If you are using Privy to manage your user authentication and wallet access via a client-side SDK, authenticated signers are entirely invisible—you do not have to manually interact with signers to create or transact with wallets.

Advanced usage

INFO

This feature is currently in development and will be available in an upcoming release.

For some advanced integrations, your app may need to interact with your users' authenticated signers directly. For example, if your app has configured wallets that require 2-of-2 quorum approvals from both the user's authorization key and a service-controlled key, you may need to collect a user signature first.

To sign with your users' authenticated signers directly, use the useAuthenticatedSigner hook. This hook exposes an interface to access the public key of the user's authenticated signer and to request signatures using the authenticated signer.

Typically, this interface is used to sign user-authenticated requests, which are then sent to the Privy wallet API. Include the resulting authorization signature as a request header when making API requests.

const { authenticatedSigner } = useAuthenticatedSigner();

// This is the public key associated with the user's authenticated signer.
authenticatedSigner.publicKey;

// Sign a wallet API request using the user's authenticated signer.
// This generates a P-256 cryptographic signature over the input.
const authorizationSignature = await authenticatedSigner.request({
  method: 'sign',
  params: walletRequestBody,
});

Authenticated signer API

INFO

This feature is currently in development and will be available in an upcoming release.

The authenticated signer API enables one-time or session-based authorization keys to be issued directly via a REST API. This API can be called from either your app's frontend or backend. You can learn more about the authenticated signer architecture here.

If applicable, first register your JWT verification public key or JWKS.json endpoint via the Privy Dashboard.

1. Make a request to the authenticated signer API using the authentication token from your JWT-based authentication system.
2. The TEE issues a one-time or session-based authenticated signer in response.
3. Use this authenticated signer as the authorization key for requests to the Privy wallet API.

Using the REST API

To authenticate your user with the authenticated signer API, make a POST request to:

https://api.privy.io/v1/signer/authenticate

TIP

In the request headers, make sure to include Privy's required authentication headers and headers that may be required for your app's wallet API setup.

Request

Include the user's authentication token as the Bearer authorization header on the request. This token is a JWT containing the user's unique identifier as the sub claim that can be verified with the registered JWT verification public key.

Response

In the response, Privy will send back the following if successful:

Field	Type	Description
authenticated_signer	string	Authorization key corresponding to the user's current authentication session, i.e. the user's authenticated signer. This is a one-time use session key.
user_id	string	The user ID associated with the authenticated user. This is a unique identifier that corresponds one-to-one with each unique sub identifier in the user's authentication token
wallet_id	string	The wallet ID associated with the authenticated user.

Example

As an example, a sample request might look like the following:

$ curl --request POST https://api.privy.io/v1/signer/authenticate \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "privy-authorization-signature: <authorization-signature-for-request>" \
-H 'Content-Type: application/json' \

A successful response will look like the following:

{
  "authenticated_signer": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgsqM8IKMlpFxVypBUa/Q2QvB1AmS/g5WHPp3SKq9A75uhRANCAATeX6BDghwclKAH8+/7IjvS1tCpvIfZ570IR44acX93pUGz5iEvpkg+HGaalHAXubuoUMq9CUWRm4wo+3090Nus",
  "user_id": "clgmdmpce0004ic08tl6qy4i9",
  "wallet_id": "clwjfdaxn0001ciy7xko7204e"
}

From here, your app may use the user's authenticated signer as the authorization key to authenticate further requests to the user's wallet.