Session keys

Session keys are a powerful feature of the Wallets API that allow you to create a session for a user's smart wallet with specific permissions. This enables secure, permissioned access to the user's smart wallet, allowing your app's server to perform actions on behalf of the user without needing their private key. Session keys allow another account to operate on a user's smart wallet with given permissions. After creating a session, you can sign transactions for the smart wallet within the defined permissions using that session key. See here for a list of permissions!

To use this guide, you'll need:

• An account you can sign with (e.g. an authentication provider or an EOA)
• An API key
• A gas manager policy ID if sponsoring gas

Create a session with permissions

The following guides demonstrate how to create and use session keys using the SDK client or by using platform-agnostic JSON-RPC APIs.

Permission types

To specify permissions during a session key installation, include them in the permissions array when calling client.grantPermission() via the SDK or wallet_createSession via the API.

// See the SDK or API guide above for full client and session key setup
const permissions = await client.grantPermissions({
  expirySec: Math.floor(Date.now() / 1000) + 60 * 60,
  key: {
    publicKey: sessionKey.address,
    type: "secp256k1",
  },
  permissions: [
    // Add one or more permission types (see below)
  ],
});

Native token transfer

This permission allows transfer of native tokens (like Ether) from the account.

{
  type: "native-token-transfer";
  data: {
    allowance: Hex; // a hexadecimal encoded transfer limit, for example, 1 ETH would be 0xde0b6b3a7640000 (1e18 in hex)
  }
}

ERC-20 token transfer

This permission allows transfer or approval of ERC-20 tokens from the account. The specified allowance represents the total cumulative spend limit for all transfers and approvals (it is not a per-operation allowance).

{
  type: "erc20-token-transfer";
  data: {
    address: Address; // erc20 token contract address
    allowance: Hex; // a hexadecimal encoded transfer limit
  }
}

Gas limit

This permission allows the session key to spend gas for transactions up to a specified limit.

{
  type: "gas-limit";
  data: {
    limit: Hex; // a hexadecimal encoded gas limit, for example 300000 gas would be 0x493e0
  }
}

Contract access

This permission grants access to all functions in a specific contract.

{
  type: "contract-access";
  data: {
    address: Address; // the target contract’s address
  }
}

Account functions

This permission grants access to specific functions on the smart wallet itself.

{
  type: "account-functions";
  data: {
    functions: Hex[]; // array of allowed function selectors, e.g. ["0xabcdef01", "0x12345678"]
  };
}

Functions on all contracts

This permission grants access to a set of function selectors across any address.

{
  type: "functions-on-all-contracts";
  data: {
    functions: Hex[]; // array of function selectors allowed globally, e.g. ["0xddf252ad"]
  };
}

Functions on contract

This permission grants access to specific function selectors on one contract.

{
  type: "functions-on-contract";
  data: {
    address: Address;  // the contract address you’re targeting
    functions: Hex[];  // array of allowed function selectors for that contract, e.g. ["0xddf252ad"]
  };
}

Root

This permission grants full access to everything. This is a very dangerous permission to grant.

{
  type: "root"; // no additional data required
}