Skip to main content

​
Architecture Overview

Cavos uses session keys bound to OAuth JWTs. Instead of storing a master private key, the SDK generates a fresh session key pair on each login that’s cryptographically linked to the user’s verified identity.

​
How Sessions Work

​
1. Session Initialization (Pre-Login)

When you call login(), the SDK: 
// Generated BEFORE OAuth redirect
const sessionPrivateKey = generateStarkKey();  // Random 252-bit key
const sessionPubKey = derivePublicKey(sessionPrivateKey);

// Compute nonce that binds the JWT to this session
const nonce = poseidon([
  sessionPubKey,
  currentBlock,
  sessionDuration,
  renewalGracePeriod,
  randomness
]);

​
2. OAuth Redirect

The nonce is included in the OAuth request to Google or Apple.

​
3. JWT Verification

When the user completes OAuth, the JWT returned contains the nonce, proving the identity is linked to that specific browser session.

​
4. On-Chain Registration

The first transaction registers the session by verifying the JWT signature and nonce on-chain.

​
Session Management

The SDK provides methods to manage your active on-chain sessions.

​
Session Renewal

Sessions have a limited duration (default 24h). Before they expire (or during the grace period), you can renew them: 
const txHash = await cavos.renewSession();
This generates a new session key pair and registers it on-chain using the old session’s authorization (while it’s still in the grace period).

​
Session Policies

Session keys can be restricted by policies to limit the damage if a session key is compromised.

​
1. Allowed Contracts

You can restrict a session key to only be able to call specific contract addresses. This is implemented using a Merkle Tree of allowed contract addresses on-chain. If a transaction attempts to call a contract not in the allowed list, the account contract will reject it.

​
2. Spending Limits

You can define maximum spending limits for specific tokens (e.g., STRK, ETH) per session. The account contract tracks the total amount spent by the session and prevents exceeding the limit.

​
Session Revocation

If you suspect a session key has been compromised, or simply want to logout securely from a shared device, you have two options:

​
1. Revoke Specific Session

Invalidates a single session key on-chain. 
const { revokeSession } = useCavos();

// Revoke current session
await revokeSession();

// Or revoke a specific session key
await revokeSession('0x123...');

​
2. Emergency Revoke All

Invalidates all currently active sessions for the wallet by incrementing the global revocation epoch. 
const { emergencyRevokeAllSessions } = useCavos();

await emergencyRevokeAllSessions();

​
Session Export/Import

For advanced use cases like command-line tools or multi-device workflows, you can export active sessions and import them elsewhere.

​
Export Session from Dashboard

Export your current active session as a base64-encoded token: 
const { exportSession, walletStatus } = useCavos();

// Only export when session is active
if (walletStatus.isSessionActive) {
  const token = exportSession();
  
  // Copy to clipboard
  navigator.clipboard.writeText(token);
  console.log('Session exported!');
}
[!WARNING] The exported token contains your session private key. Store it securely and never share it publicly.

​
Import Session in CLI

Once exported, the session can be used in the Cavos CLI without any login: 
# Set as environment variable
export CAVOS_TOKEN="<base64_token>"

# Or import directly
cavos session import <base64_token>

# Execute commands
cavos balance
cavos transfer --to 0x... --amount 1.5 --token STRK --wait
cavos approve --spender 0x... --amount 100 --token STRK

​
Use Cases

  1. AI Agents: Export session from your dashboard, give it to an AI agent for autonomous trading/transactions
  2. CI/CD Pipelines: Automate on-chain deployments without manual signing
  3. Multi-Device: Use the same session on desktop dashboard and mobile/server CLI
  4. Batch Operations: Execute multiple transactions quickly from command line
[!NOTE] Exported sessions have the same policies (spending limits, allowed contracts) as configured in the dashboard.
  • Non-Custodial: Neither Cavos nor the application ever sees your session private key. It lives only in your browser’s memory.
  • Auto-Expiry: Sessions automatically expire, minimizing the impact of a lost device or session key.
  • Per-App Isolation: Each app uses a different derivation salt, so a session key for App A cannot sign for App B.
  • Enforced Policies: Even if a session key is stolen, the attacker is limited by the allowed contracts and spending limits defined at session creation.