Wallets
Session Keys Guide
Session keys enable secure transaction execution on behalf of accounts without requiring direct access to the main account's private key. This guide covers session keys for both ERC-4337 smart accounts and ERC-7702 smart EOAs (Externally Owned Accounts).
Before you begin, ensure you have:
- A thirdweb client configured
- An in-app wallet with ERC-7702 support
- A session key account address (can be generated or an existing wallet)
First, let's set up the necessary imports and configuration:
Create an in-app wallet configured with ERC-7702 execution mode:
The executionMode
option allows you to configure the wallet behavior:
mode
: Set to"EIP7702"
for EIP-7702 upgraded EOA functionalitysponsorGas
: Enable gas sponsorship for gasless transactions
Create a contract instance for the deployed smart EOA:
Add a session key with full execution permissions:
account
: The admin account that will create the session keycontract
: The smart EOA contract instancesessionKeyAddress
: The address that will be granted session key permissionsdurationInSeconds
: How long the session key should be valid (in seconds)grantFullPermissions
: Iftrue
, grants unrestricted access. Iffalse
, you must specify policies.
For more fine-grained control, you can specify call and transfer policies:
Control which smart contract calls the session key can make:
target
: The contract address the session key can callselector
: The function selector (4-byte identifier) that can be calledmaxValuePerUse
: Maximum ETH value that can be sent per transactionvalueLimit
: Total value limits over timeconstraints
: Parameter-level constraints for function calls
Control native token transfers the session key can make:
target
: The recipient address for transfersmaxValuePerUse
: Maximum wei per individual transfervalueLimit
: Total transfer limits over time
Once created, the session key can be used with Engine or other server-side execution:
Here's a complete example for setting up and using a session key with ERC-7702:
- Session Key Storage: Store session keys securely, preferably in a vault system
- Permission Scope: Use granular permissions (
grantFullPermissions: false
) for production use cases - Time Limits: Set appropriate
durationInSeconds
values based on your use case - Policy Design: Carefully design call and transfer policies to minimize risk
- Key Rotation: Regularly rotate session keys and revoke unused ones
- Monitoring: Monitor session key usage for suspicious activity
- Account not deployed: Ensure you've sent a transaction to trigger the account deployment/upgrade
- Invalid signature: Make sure the admin account is properly authenticated and can sign typed data
- Permission denied: Verify the session key has the necessary policies for the operation
- Expired session key: Check that the current time is within the session key's validity period
- Learn more about In-App Wallets
- Explore the API Reference
- Check out the TypeScript SDK documentation