Access Keys Reference

Access keys are secure tokens that allow clients to verify subscription status without exposing sensitive Stripe data.

Format

interface AccessKey {
  /** The access key string in format ak_xxxxx */
  key: string;
  
  /** Associated subscription ID */
  subscriptionId: string;
  
  /** When the key was created */
  createdAt: string;
  
  /** When the key expires */
  expiresAt: string;
}

Lifecycle

stateDiagram-v2
    [*] --> Created: Generate
    Created --> Active: Checkout Complete
    Active --> Expired: Time Limit
    Active --> Rotated: Update
    Rotated --> [*]
    Expired --> [*]

Key Generation

Access keys are generated:

1. When creating a checkout session
2. When changing subscription plans
3. During key rotation
4. On manual refresh

Storage Guidelines

Client-Side

// Store key securely
localStorage.setItem('stripe_key_' + subscriptionId, accessKey);

// Clear on logout
function logout() {
  Object.keys(localStorage)
    .filter(k => k.startsWith('stripe_key_'))
    .forEach(k => localStorage.removeItem(k));
}

Security Considerations

• Never store keys server-side
• Clear keys on logout
• Rotate keys regularly
• Validate key format
• Handle expiration gracefully

Validation

// Validate key format
function isValidKey(key: string): boolean {
  return /^ak_[a-zA-Z0-9]{32}$/.test(key);
}

// Check expiration
function isExpired(key: AccessKey): boolean {
  return new Date(key.expiresAt) < new Date();
}

Error Handling

Common error codes when working with access keys:

Code	Description	Resolution
6778003	Invalid access key	Request new key
6778004	Expired access key	Refresh key
6778005	Key not found	Create new checkout
6778006	Invalid format	Check key format

Best Practices

1. Key Storage

   • Store securely client-side
   • Clear on logout
   • Never transmit in URLs
   • Don't log key values

2. Validation

   • Check format before use
   • Validate expiration
   • Handle errors gracefully
   • Refresh proactively

3. Security

   • Use HTTPS only
   • Rotate regularly
   • Monitor usage
   • Log access patterns

4. Error Handling

   • Retry on failure
   • Refresh expired keys
   • Clear invalid keys
   • Guide user recovery