Session Keys Guide
Session keys enable secure transaction execution on behalf of smart accounts without requiring direct access to the main account's private key. This guide will walk you through creating and using session keys with the thirdweb TypeScript SDK.
Before you begin, ensure you have:
- A thirdweb client configured
- Access to a session key account address
- Vault access token for Engine operations
First, let's set up the necessary imports and configuration:
The first step is to add our session key address as a signer to the user's smart account. This is typically done on the client side since it needs explicit user approval. This can be done by configuring the smart wallet with the session key address and permissions.
In a React application, this can be done by using the ConnectButton
or ConnectEmbed
component. This will automatically configure the smart wallet with the session key address and permissions.
This can also be done in pure TypeScript by using the smartWallet
function and connecting it to a personal account.
For this guide, we'll generate a random personal account that will be used to create the smart wallet:
The permissions
object allows you to control what the session key can do:
approvedTargets
: Specify which contract addresses the session key can interact with- Use
"*"
for all targets - Use an array of addresses for specific contracts:
["0x123...", "0x456..."]
- Use
Connect the smart wallet using the personal account:
Note that in a React application, this would be done automatically by the ConnectButton
or ConnectEmbed
component.
Check that the session key is properly registered as an active signer:
Set up an Engine server wallet using the session key for transaction execution:
entrypointVersion
: The ERC-4337 entrypoint version to usesignerAddress
: The session key address that will sign transactionssmartAccountAddress
: The smart account address that will execute transactionstype
: The account abstraction type (ERC4337)
Now you can execute transactions using the session key:
Here's a complete example putting it all together:
- Session Key Storage: Store session keys securely, preferably in a vault system
- Permission Scope: Limit session key permissions to only necessary targets
- Key Rotation: Regularly rotate session keys for enhanced security
- Monitoring: Monitor session key usage for suspicious activity
- Session key not active: Ensure the session key is properly registered with the smart account
- Permission denied: Check that the target address is included in
approvedTargets
- Gas estimation failed: Verify that gas sponsorship is properly configured
- Vault token invalid: Ensure your vault access token is valid and has proper permissions
Always wrap your session key operations in try-catch blocks:
- Learn more about Smart Wallets
- Explore Engine API Reference
- Check out the TypeScript SDK documentation