Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cloud.coinbase.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Understanding how user sessions work with CDP wallets is crucial for building secure applications with proper authentication flows. Sessions are managed through a dual-token system designed to balance security and user experience.

​
Session duration

User sessions are managed through a dual-token system:
  • Maximum session length: 7 days
  • Access token expiry: 15 minutes
  • Refresh token expiry: 7 days

​
How session tokens work

When a user successfully authenticates, they receive:
  1. Access token: Short-lived (15 minutes) token used for API requests
  2. Refresh token: Long-lived (7 days) token used to obtain new access tokens
The refresh token automatically generates new access tokens as needed, providing seamless authentication for up to 7 days. After 7 days, users must re-authenticate.

​
Session lifecycle

  1. User completes email/SMS OTP verification or other authentication method
  2. System issues both access and refresh tokens
  3. User gains immediate access to their wallet
  4. Session remains active for up to 7 days with automatic token refresh
  • Access tokens are automatically refreshed using the refresh token
  • Applications continue working without interruption
  • After 7 days, the refresh token expires
  • User must complete authentication again

​
Implementation considerations

  • Monitor authentication state using onAuthStateChange() to handle session expiration
  • Implement graceful fallback when tokens expire
  • Consider showing session timeout warnings to users approaching the 7-day limit
  • Test your application’s behavior when refresh tokens expire

​
Sign out functionality

Always provide a clear way for users to sign out using the signOut() method from @coinbase/cdp-core or the AuthButton component which handles sign out automatically. For React applications, you can also use the useSignOut hook: 
import { useSignOut } from '@coinbase/cdp-hooks';

function SignOutButton() {
  const { signOut } = useSignOut();
  return <button onClick={signOut}>Sign Out</button>;
}

​
Custom authentication sessions

If you’re using custom authentication with your own identity provider, session management works differently:
  • Token lifecycle: Managed by your identity provider (Auth0, Firebase, etc.)
  • No CDP token refresh: CDP always requests a fresh JWT via the getJwt callback
  • Session duration: Controlled by your IDP’s configuration
  • Sign out: Only need to sign out from your IDP
For more details on custom authentication, see the Custom Authentication guide.