Register an application in Xero Developer Portal and obtain client_id and client_secret; set the redirect URI for the authorization code flow
Redirect the user to https://login.xero.com/identity/connect/authorize with scopes including 'openid profile email accounting.transactions offline_access'
Exchange the authorization code at https://identity.xero.com/connect/token for an access token and refresh token; store both securely per-tenant
Call GET https://api.xero.com/connections to retrieve the list of Xero organisations (tenants) the user has connected; each has a 'tenantId'
Include the 'Xero-Tenant-Id' header on every API call set to the target tenantId; omitting it causes a 403
Use the refresh token to obtain a new access token before expiry; handle 400 errors on token refresh by prompting the user to reconnect
Known gotchas
Xero access tokens have a short lifetime (consult current docs for the exact duration); do not cache them without a refresh strategy
A single OAuth flow can grant access to multiple organisations; you must present the user with an organisation picker and store tokens per tenantId
If a user disconnects your app from Xero's connected apps page, subsequent refresh token requests will fail with an invalid_grant error; detect this and prompt re-authorization rather than retrying indefinitely
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp