Token Expiration

Understanding and resolving token expiration issues.

What Are Tokens?

When you connect HubSpot or QuickBooks, you authorize SimpleCommerceSync to access your data. This authorization creates "tokens" - digital keys that prove we have permission.

Tokens are like temporary passwords that:

  • Grant access to your data
  • Expire after a set time (for security)
  • Can be refreshed automatically

How Token Refresh Works

Automatic Refresh

SimpleCommerceSync automatically refreshes tokens:

  • Tokens are checked regularly (every 30 minutes)
  • Before they expire, we request new tokens
  • This happens in the background - you don't need to do anything

When Automatic Refresh Fails

Sometimes refresh can fail due to:

  • Network issues during refresh
  • Account changes in HubSpot/QuickBooks
  • Revoked permissions
  • Extended period of inactivity

Signs of Token Problems

In the Dashboard

  • Connection status shows "Disconnected" or "Error"
  • Warning message about connection issues

In Sync Logs

  • Multiple syncs failing with "Unauthorized" errors
  • Error messages mentioning "token" or "authentication"

Resolving Token Issues

Step 1: Check Connection Status

  1. Go to Settings then Connections
  2. Look at the status for HubSpot and QuickBooks
  3. Note which connection has issues

Step 2: Reconnect

  1. Click Disconnect for the affected connection
  2. Click Connect to start fresh
  3. Complete the authorization flow
  4. Verify status shows "Connected"

Step 3: Verify Syncs Resume

  1. Go to Data and check recent sync logs
  2. New syncs should process normally
  3. Previously failed syncs can be retried

Preventing Token Issues

Keep Accounts Active

  • Maintain active HubSpot and QuickBooks subscriptions
  • Log into both platforms periodically
  • Don't let accounts become dormant

Don't Revoke App Access

Avoid revoking SimpleCommerceSync access from:

  • HubSpot Connected Apps settings
  • Intuit account management

If you revoke access, you'll need to reconnect.

Password Changes

If you change your HubSpot or QuickBooks password:

  • Existing connections may continue working
  • If issues occur, reconnect the affected service

HubSpot Token Details

  • Access tokens expire after 6 hours
  • Refresh tokens are used to get new access tokens
  • SimpleCommerceSync refreshes before expiration

QuickBooks Token Details

  • Access tokens expire after 1 hour
  • Refresh tokens expire after 100 days (if unused)
  • Regular syncing keeps tokens fresh

Troubleshooting Specific Errors

"Token expired" or "Invalid token"

  1. Go to Settings then Connections
  2. Disconnect the affected service
  3. Reconnect immediately

"Refresh token expired"

This means the connection was inactive too long:

  1. Disconnect the connection
  2. Reconnect and re-authorize

"Access denied" or "Insufficient permissions"

Permissions may have changed:

  1. Disconnect the connection
  2. Reconnect and carefully review permissions
  3. Ensure all required permissions are granted

Repeated token failures

If tokens keep expiring:

  1. Check your HubSpot/QuickBooks account status
  2. Verify no account restrictions
  3. Contact support if issues persist

Getting Help

If you've tried reconnecting and still have issues:

  1. Note the error messages you see
  2. Check when the problem started
  3. Verify account access in HubSpot/QuickBooks directly
  4. Contact support with these details