Laravel Xero Oauth2 Laravel Package

Product Decisions This Supports

• Build vs. buy for accounting connectivity. This package makes a Xero integration a days-not-months decision. It gives a Laravel app the OAuth 2.0 handshake, token persistence, and refresh mechanics that would otherwise consume a sprint or two of senior engineering time — time better spent on the differentiating workflow around the data.
• Feature feasibility and roadmap sizing. Anything that reads or writes Xero data sits on top of this: invoice and bill sync, contact/customer import, payment status, chart-of-accounts mapping, P&L or aged-receivables reporting surfaces, reconciling Xero transactions against your own ledger. Its presence moves these from "requires an integration platform" to "requires a controller and a job."
• Multi-tenant connectivity model. Xero tokens are per-organisation, not per-user, and a single customer may connect several Xero orgs. The decisions this drives: one connection per tenant, a "Connect Xero" onboarding step, scope selection (accounting transactions vs. contacts vs. settings vs. payroll), and what happens on the settings page when a token is revoked from the Xero side. These are product-surface decisions, not just engineering ones.
• Use cases this unlocks: vertical SaaS for bookkeepers and accountants, e-commerce/finance reconciliation tools, expense and AP automation, SMB cash-flow dashboards, and internal finance ops where Laravel is already the house stack.
• Scope discipline. Adopting this is a standing decision not to rebuild accounting, and not to over-build a generic Xero abstraction layer, until a second accounting provider is genuinely on the roadmap.
• Where the value actually is. The OAuth dance looks trivial and isn't — refresh-token rotation, revocation, and per-org token storage are exactly the fiddly parts that generate support tickets. Buying that correctness is the real product win; the API calls are the easy part.

When to Consider This Package

Adopt when:

• The application is Laravel (roughly 8+), PHP-native, and you want a connector that behaves like the rest of your stack — service provider, config file, migrations, Eloquent — rather than a framework-agnostic SDK bolted on.
• You need per-tenant Xero connections with token storage and refresh handled for you, including the rotating refresh-token behaviour Xero introduced.
• Your Xero surface is scoped: sync a defined set of entities on a defined cadence. This is a connector, not a sync engine — you own the queueing, backoff, conflict resolution, and idempotency on top.
• You can accept a small, permissively licensed dependency (MIT) with the discipline to pin, review, and potentially vendor/fork it.

Look elsewhere when:

• You are not on Laravel. Use Xero's official SDK or a Saloon/PHP HTTP client built directly against the Xero API.
• You need webhooks, payroll, complex bidirectional sync orchestration, rate-limit budgeting across many orgs, or historical backfill at scale. Budget for an internal integration layer regardless of which client library sits underneath.
• You require vendor SLA, indemnification, or a named maintainer on call. At this adoption level you are effectively self-supporting; that is a procurement decision, not a technical one.
• The team already standardises on a connector framework (Saloon, Laravel Socialite-style providers, an internal integration platform). Introducing a one-off dependency for one provider creates a maintenance seam you will pay for later.
• You cannot tolerate single-maintainer supply-chain risk and are unwilling to fork. Then treat this as reference material — read it, copy the token-refresh logic, own it.

How to Pitch It (Stakeholders)

For executives: We can ship a Xero integration in days instead of building OAuth plumbing from scratch, at zero licence cost and with no lock-in. It converts a recurring "when are we getting Xero?" roadmap item into a scheduled piece of work, and it lets us sell into the accountant/bookkeeper segment that lives inside Xero. The exposure is proportionate to the size of the dependency — small, MIT-licensed, and swappable — providing we wrap it behind our own interface rather than calling it from everywhere.

For engineering: It handles the OAuth 2.0 authorisation-code flow, token persistence, and refresh-token rotation, and hands back an authenticated client for Xero API calls. It deliberately stops at the connector boundary — scheduling, retries, rate limiting across orgs, and data mapping remain ours. It is a small, low-traffic repository, so we should pin the version, review the source before merge, and isolate it behind a single internal service so replacing it later is a one-file change rather than a refactor. Read it before adopting it; the token refresh logic is the part worth understanding even after we install it.