User authorization keys enable users to fully control self-custodial wallets.

Authorization keys are the core primitive for control of Privy’s wallet API. Authorization key signatures are used to authenticate directly with the Privy wallet API.

They enable a fully configurable control model for wallets, which includes the entire spectrum from user-custodial wallets to powerful service-level controls. If an authorization key is set as a signer on the wallet, than it can transact funds on the wallet.

​
Self-custodial wallets

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

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

  • Authenticating a user with the User authorization key API to issue an authorization key
  • Directly adding the user’s passkey as the authorization key

User authorization keys are authorization keys that users control directly via an authentication method. Privy infrastructure manages issuing session-based authorization keys to users via the User authorization key API. This configuration results in cryptographically-enforced user custody of wallets.

​
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 user authorization key API ensures that if a user is logged in, they always have access to their wallet.

​
Multi-factor authentication

Privy also enables multi-factor authentication for access to user authorization keys. Supported additional factors include:

  • Authenticator apps (TOTP)
  • Biometric verification (passkeys)
  • SMS confirmation
  • Hardware security keys

This means your app can require additional user verification for sensitive wallet operations. Learn more

​
Client-side user authorization keys

Client-side user authorization keys 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. User authorization keys are only accessible when the user is authenticated.

Client-side authorization keys are managed within the secure environments directly on user devices. In particular, Privy secures user authorization keys using browser-enforced isolation via iframes. The Privy iframe runs in a separate process with its own isolated memory space, completely separated from your application.

Client-side authorization keys are generated directly on the user’s device, secured using distributed key sharding, and persisted with Privy’s key management infrastructure. See user device execution environment for more information about this architecture. Note this core architecture can be used to secure either user authorization keys or on-device wallets directly.

​
User authorization key API

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

The User authorization key 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.

The User authorization key API manages authorization keys from within trusted execution environments (TEEs)—see TEE architecture for more information. This API integrates with any asymmetric JWT-based authentication system, such as Privy’s native authentication system, Auth0, Firebase, or any OIDC or OAuth authentication provider. Authentication is verified within the TEE.

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

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

​
Additional encryption

Additionally, the user authorization keys response can be further encrypted. While all key responses are protected by TLS, you can ensure the key is encrypted from the TEE to the client using HPKE (Hybrid Public Key Encryption), using the same method used by our wallet export API.

Was this page helpful?