Authorizing actions with granular MFA

To authorize an action that requires MFA, your app’s server verifies the user’s MFA, then passes the MFA token with the user’s JWT in user_auth. The SDK exchanges them for a user key that records the MFA, and signs the request with it. The user must be enrolled in MFA first. See enrollment with server-side MFA.

Pass the MFA token in user_auth

Send the user an SMS code, then verify it to get an MFA token. TOTP and passkeys work the same way. See server-side MFA.

This requires @privy-io/node version 0.39.0 or later.

// Sends a 6-digit code to the user's enrolled phone number
await privy.users().mfa.sms.verification.init(userId, {user_jwt: userJwt});

// After the user receives the code
const {token: mfaToken} = await privy.users().mfa.sms.verification.verify(userId, {
  code: '123456',
  user_jwt: userJwt
});

// Pass this as the authorization_context of any wallet request
const authorizationContext = {
  user_auth: [{user_jwt: userJwt, mfa_token: mfaToken}]
};

The MFA token lasts for the cache duration. Pass the latest token on every request that may require MFA.

Examples

Each example shows a policy that requires MFA for the action, then the request with the authorizationContext from above.

Export a wallet

Exporting a private key or seed phrase requires MFA. This is the policy from setup.

{
    "version": "1.0",
    "name": "Require MFA for wallet export",
    "chain_type": "ethereum",
    "rules": [
        {
            "name": "Require MFA for private key export",
            "method": "exportPrivateKey",
            "conditions": [],
            "action": "ALLOW_WITH_MFA"
        },
        {
            "name": "Require MFA for seed phrase export",
            "method": "exportSeedPhrase",
            "conditions": [],
            "action": "ALLOW_WITH_MFA"
        },
        {
            "name": "Allow everything else",
            "method": "*",
            "conditions": [],
            "action": "ALLOW"
        }
    ]
}

The SDK decrypts the exported key for you.

const {private_key} = await privy.wallets().exportPrivateKey(walletId, {
  authorization_context: authorizationContext
});

Sign a message

Signing any message requires MFA.

{
    "version": "1.0",
    "name": "Require MFA for message signing",
    "chain_type": "ethereum",
    "rules": [
        {
            "name": "Require MFA to sign messages",
            "method": "personal_sign",
            "conditions": [],
            "action": "ALLOW_WITH_MFA"
        },
        {
            "name": "Allow everything else",
            "method": "*",
            "conditions": [],
            "action": "ALLOW"
        }
    ]
}

const {signature} = await privy.wallets().ethereum().signMessage(walletId, {
  message: 'Hello, world!',
  authorization_context: authorizationContext
});

Send a transaction

Sending more than 1 ETH requires MFA.

{
    "version": "1.0",
    "name": "Require MFA for large ETH transfers",
    "chain_type": "ethereum",
    "rules": [
        {
            "name": "Require MFA for transfers over 1 ETH",
            "method": "eth_sendTransaction",
            "conditions": [
                {
                    "field_source": "ethereum_transaction",
                    "field": "value",
                    "operator": "gt",
                    "value": "0xDE0B6B3A7640000" // 1 ETH in wei
                }
            ],
            "action": "ALLOW_WITH_MFA"
        },
        {
            "name": "Allow everything else",
            "method": "*",
            "conditions": [],
            "action": "ALLOW"
        }
    ]
}

const {hash} = await privy
  .wallets()
  .ethereum()
  .sendTransaction(walletId, {
    caip2: 'eip155:8453',
    params: {
      transaction: {
        to: '0xRecipientAddress',
        value: '0x1BC16D674EC80000', // 2 ETH in wei
        chain_id: 8453
      }
    },
    authorization_context: authorizationContext
  });

Update a wallet

Changing a user-owned wallet’s policies or signers requires the user’s MFA, with or without a policy. See resource updates.

const wallet = await privy.wallets().update(walletId, {
  policy_ids: [policyId],
  authorization_context: authorizationContext
});

Authentication

Using Privy authentication

Using your own authentication

Using MFA

Authorizing actions with granular MFA

Pass the MFA token in user_auth

Examples

Export a wallet

Sign a message

Send a transaction

Update a wallet

​Pass the MFA token in user_auth

​Examples

​Export a wallet

​Sign a message

​Send a transaction

​Update a wallet

Pass the MFA token in user_auth

Examples

Export a wallet

Sign a message

Send a transaction

Update a wallet