Permissions & Session Keys
Manage permissions and session keys for secure B3 Global Account interactions
B3 Global Accounts are deprecated. Upside and AnySpend now sign in with your own wallet. If you held funds in a Global Account and need help, ask in the B3 Discord. The team never DMs first and will never ask for your seed phrase or private key.
Overview
Session keys and permissions provide a secure way to allow applications to perform actions on behalf of users without requiring constant authentication. This is particularly useful for games and applications that need to execute transactions automatically.
Permission System
Permission Types
B3 Global Accounts support granular permissions that can be configured for different use cases:
- Contract Interactions: Specify which smart contracts can be called
- Token Limits: Set spending limits for native tokens and ERC-20 tokens
- Time Restrictions: Define start and end dates for permissions
- Transaction Limits: Control the maximum value per transaction
Permission Structure
typescriptinterface Permissions { approvedTargets: string[]; // Contract addresses startDate: Date; // When permissions become active endDate: Date; // When permissions expire nativeTokenLimitPerTransaction: number; // ETH limit per tx // Additional ERC-20 token limits can be added}
Session Key Implementation
Basic Permission Request
tsximport { RequestPermissionsButton } from "@b3dotfun/sdk/global-account/react";const b3Chain = { id: 8453, name: "Base", nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 }, rpc: "YOUR_BASE_RPC_URL",};function BasicPermissions() { const permissions = { approvedTargets: [ "0x...", // Your game contract ], startDate: new Date(), endDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days nativeTokenLimitPerTransaction: 0.01, // 0.01 ETH per transaction }; return ( <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." // MetaMask or wallet address permissions={permissions} onSuccess={() => { console.log("Permissions granted successfully!"); }} onError={async (error) => { console.error("Permission request failed:", error); }} /> );}
Game-Specific Permissions
For gaming applications, you might need broader permissions:
tsxfunction GamePermissions() { const gamePermissions = { approvedTargets: [ "0x...", // Game contract "0x...", // NFT marketplace "0x...", // Token contract ], startDate: new Date(), endDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days nativeTokenLimitPerTransaction: 0.001, // Small ETH limit for gas }; return ( <div className="game-permissions"> <h3>Grant Game Permissions</h3> <p>Allow this game to perform actions on your behalf for 7 days</p> <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." permissions={gamePermissions} onSuccess={() => { // Redirect to game or update UI console.log("Game permissions granted!"); }} onError={async (error) => { console.error("Failed to grant game permissions:", error); }} /> </div> );}
Advanced Permission Patterns
Dynamic Permission Updates
tsximport { useState } from "react";function DynamicPermissions() { const [permissionLevel, setPermissionLevel] = useState<'basic' | 'advanced'>('basic'); const getPermissions = (level: string) => { const basePermissions = { startDate: new Date(), endDate: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours }; if (level === 'basic') { return { ...basePermissions, approvedTargets: ["0x..."], // Limited contracts nativeTokenLimitPerTransaction: 0.001, }; } else { return { ...basePermissions, approvedTargets: ["0x...", "0x...", "0x..."], // More contracts nativeTokenLimitPerTransaction: 0.01, }; } }; return ( <div> <div className="permission-selector"> <button onClick={() => setPermissionLevel('basic')} className={permissionLevel === 'basic' ? 'active' : ''} > Basic Permissions </button> <button onClick={() => setPermissionLevel('advanced')} className={permissionLevel === 'advanced' ? 'active' : ''} > Advanced Permissions </button> </div> <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." permissions={getPermissions(permissionLevel)} onSuccess={() => console.log(`${permissionLevel} permissions granted`)} /> </div> );}
Security Best Practices
Error Handling
onError receives the Error from a failed request. The SDK defines no error codes, so handle every failure the same way:
tsxfunction PermissionErrorHandling() { const handlePermissionError = async (error: Error) => { console.error("Permission request failed:", error.message); }; return ( <RequestPermissionsButton chain={b3Chain} sessionKeyAddress="0x..." onError={handlePermissionError} /> );}