OAuth vs API key vs webhook: understanding authentication patterns for accounting and commerce integrations

If you're building integrations with accounting or commerce platforms, one of the first technical decisions you'll face is how authentication works. The answer isn't always straightforward because each platform handles it differently, and the authentication pattern you use affects your product's security, user experience, and long-term maintenance burden.

We've built integrations with over 40 platforms across accounting, commerce, and payments, and each one handles authentication in its own way. This guide walks through the three primary authentication patterns you'll encounter when building financial data integrations: OAuth 2.0, API keys, and webhook-based connections. We cover how each works, where you'll run into each one, and the practical considerations for building a production-grade integration.

OAuth 2.0: the modern standard

OAuth 2.0 is the authentication standard used by most modern SaaS platforms, including QuickBooks Online, Xero, Shopify, Stripe, and Amazon Seller Central. It allows a user to grant your application access to their data without sharing their credentials directly.

How it works

Your application redirects the user to the platform's authorization page. The user reviews the permissions your application is requesting and grants access. The platform redirects back to your application with an authorization code. Your application exchanges the code for an access token and a refresh token. You use the access token for API requests and the refresh token to get new access tokens when they expire.

Key considerations for developers

Token expiration and refresh logic are the most common source of production issues we've seen across our customer base. Access tokens typically expire in 30 to 60 minutes. If your refresh logic fails, your connection goes dead and you stop receiving data. Build robust token refresh with error handling and alerting.

Scope management varies by platform. QuickBooks and Xero allow granular scope control, meaning you can request only the permissions your application needs. Some platforms have all-or-nothing permission models. Request the minimum scope necessary for your use case.

Redirect URI validation is strict on most platforms. Your redirect URI must match exactly what is registered with the platform. Mismatched URIs are one of the most frequent causes of authentication failures during development, and it's the kind of issue that's easy to overlook when you're setting up your first integration.

Rate limits after authentication vary significantly. QuickBooks Online allows roughly 500 requests per minute per connection. Xero has specific rate limits by endpoint. NetSuite limits depend on the account's license tier. Understanding these limits is essential for designing your data sync architecture, and it's one of the reasons we store data locally rather than operating as a passthrough, so our customers' applications aren't constrained by the underlying platform's rate limits.

API keys: simple but limited

Some platforms, particularly older or on-premise systems, use API key-based authentication. This is simpler than OAuth but comes with tradeoffs.

How it works

The user generates an API key or set of credentials within their platform account and provides them to your application. Your application includes these credentials in API request headers.

Where you encounter this

QuickBooks Desktop integrations often use credential-based or Web Connector approaches rather than OAuth. Some ERP systems, particularly on-premise deployments of NetSuite or SAP, use API keys or token-based authentication that requires manual configuration by the customer's administrator.

Key considerations

Security responsibility shifts to the user. Unlike OAuth, where tokens are managed programmatically and can be revoked centrally, API keys are typically static credentials that don't expire. If a key is compromised, it remains valid until the user manually rotates it.

User experience is worse. Instead of a one-click OAuth flow, the user has to navigate to their platform's settings, generate credentials, copy them, and paste them into your application. This adds friction to onboarding and increases support requests. We've found this to be a significant factor in connection completion rates: the more manual steps required, the more drop-off you see during onboarding.

For production applications that need to onboard customers at scale, API key-based authentication creates more support burden and security risk than OAuth-based flows. A unified API can abstract over this: your customer goes through a single authentication widget, and the provider handles whatever authentication mechanism the underlying platform requires, whether that's OAuth 2.0, API keys, or something more specialized like the Web Connector approach needed for QuickBooks Desktop.

Webhooks: real-time data delivery

Webhooks aren't an authentication mechanism in themselves, but they're a critical component of any integration architecture, and they have their own authentication patterns.

How webhooks work

When an event happens on the platform, like an order being placed, an invoice being created, or a payment being processed, the platform sends an HTTP POST request to a URL you specify. Your application receives the event payload and processes it.

Webhook authentication

Most platforms sign webhook payloads using HMAC-SHA256 or a similar algorithm, allowing your application to verify that the webhook came from the expected source. Always validate webhook signatures. Unverified webhooks are a vector for data injection and spoofing attacks.

Key considerations

Webhook reliability varies dramatically by platform. Some platforms guarantee at-least-once delivery with retry logic. Others send the webhook once and move on, meaning you lose the event if your endpoint is temporarily down. Build your webhook handler to be idempotent, meaning processing the same event twice doesn't create duplicate data, and implement a reconciliation mechanism to catch missed events. We generate our own webhooks on top of the underlying platform webhooks, which gives our customers more consistent real-time event delivery across all platforms regardless of how reliable the underlying platform's webhook system is.

Webhook payloads also vary in completeness. Some platforms send the full object in the webhook payload. Others send only an event type and object ID, requiring you to make a follow-up API call to fetch the actual data. Understanding the payload structure for each platform determines how you design your event processing pipeline.

Putting it all together

In practice, most integrations use a combination of these patterns. OAuth for initial authentication, regular API calls for historical data sync, and webhooks for real-time updates. The challenge is that each platform implements these patterns slightly differently, and the edge cases compound when you support multiple platforms.

A unified API abstracts over all of this. Your customer authenticates once through a single widget. The provider handles OAuth, token refresh, API keys, and webhook management for every underlying platform. Your application receives normalized data through a single API and normalized webhooks through a single endpoint.

For teams that need to move quickly, this abstraction eliminates weeks of platform-specific authentication engineering and ongoing maintenance. For teams that want full control, understanding these patterns is essential for making informed build-versus-buy decisions and for debugging issues when they arise in production.

‍