How Xero OAuth and Connection Management Works

Source: xero_controller.rb, company.rb

• OAuth2 callback requires a valid authorization code; if auth fails, the user is redirected to a static 404-xero.html page with no error detail — the actual error is only written to EventLog
• Sign-up validates a single-use unlock code; on successful sign-up the code is regenerated, so any previously shared link becomes invalid
• When connecting to a multi-org Xero account, the system defaults to the FIRST tenant (index 0) — customers with multiple Xero organisations may silently connect to the wrong one
• A user can only link their company to Xero once; to re-link or switch tenants they must fully disconnect first
• Xero client credentials (client ID and secret) differ between production and development environments — using the wrong pair produces opaque auth failures
• Xero connection validity is checked by whether the stored token can actually be decrypted, not just whether a token exists

Support scenarios

• "I connected Xero but it's syncing to the wrong organisation" → The system picked the first tenant (index 0). Customer needs to disconnect and reconnect, ensuring the correct org is listed first or selecting it during reconnection.
• "I clicked the Xero link and got a 404 page" → Auth failed silently. Check EventLog for the real error — common causes are expired auth codes, invalid credentials, or mismatched environment settings.
• "My Xero sign-up link isn't working anymore" → Unlock codes are single-use. Once someone has successfully signed up, the code is regenerated. A new link needs to be issued.