Getting started · Step 2 of 3
Connect Xero
Read-only access first — write access only when you approve an action. Five minutes.
Start the connect flow
From your signed-in dashboard, click Connect Xero. Compass redirects you to Xero's official OAuth 2.0 consent screen. Sign in with your Xero credentials (Compass never sees them) and pick the organisation you want to scan.
Read scopes we request at connect
Every scope below is read-only. Xero displays the same list on the consent screen — cross-check that we are asking for these and only these:
accounting.contacts.read- Reads client and supplier contact records — the names Compass shows in insights.
accounting.transactions.read- Reads invoices, payments, credit notes, bills, quotes and bank transactions. This is where the deterministic maths lives.
accounting.reports.read- Reads standard Xero reports (Profit & Loss, Balance Sheet) that back the runway and drawings-vs-profit signals.
payroll.employees.read- Reads posted pay runs so the runway metric can subtract payroll from monthly burn. If you have no payroll, no data is returned and the signal falls back to bill-only burn.
offline_access- Standard OAuth 2.0 refresh-token scope. Compass refreshes silently in the background so you do not have to re-consent every 30 minutes.
What we do NOT ask for at connect.
No accounting.contacts (write), no
accounting.transactions (write), no banking scopes, no admin scopes.
Compass cannot change anything in your Xero from a fresh connection — the read
story is the entire footprint at that point.
What happens when Xero calls back
Xero redirects to a locale-agnostic Compass callback URL. Compass:
- Verifies the OAuth
stateparameter against the one we minted at start. - Exchanges the code for an access token + refresh token.
- Encrypts the token bundle with a customer-managed KMS key, binding it to your Cognito user ID as the encryption context — a leaked ciphertext cannot decrypt against anyone else's identity.
- Stores the ciphertext in DynamoDB in the AWS London region (
eu-west-2). - Redirects you back to the dashboard, connected.
Write scopes: on-demand, per action, always advisory
When you click Approve on a drafted action — say, a chase email
logged against a contact — Compass raises a fresh Xero consent for the narrow
write scope needed (accounting.contacts or
accounting.transactions). You can dismiss the consent and no write
happens. Every approval writes an audit-log entry (12-month rolling retention);
every write is idempotent, so a nervous double-click never posts twice.
Multi-org support
You can connect more than one Xero organisation to a single Compass account. Credits pool at the user level; Compass Pro subscriptions are per-organisation so you only pay for the orgs you scan often.
Disconnecting
Disconnect any time from /uk/account. We tombstone the token bundle immediately (the KMS ciphertext becomes unrecoverable) and stop scanning. Your cached scans stay viewable so you can keep referring back to conclusions you already made.