OAuth vs API Keys for Business Integrations

Authentication is not a login screen. It is how your job proves it is allowed to write an order at 3am when nobody is at a keyboard. Palmate’s API integration designs pick the grant the vendor actually supports — then make rotation, expiry, and least privilege boring.

This sits on the API integration checklist under secrets. It is worth its own page because “we will use OAuth” is not a design.

API keys are still a valid production design

A static key (header, query, HMAC secret) is simple: the server holds a secret, calls the vendor, rotates on a calendar. It fits machine-to-machine jobs: nightly sync, warehouse adapter, a backend that is the only client.

Keys fail when:

• They are shared across staging and production.
• They are pasted into chat or committed to git.
• They are god-mode: one key can refund, delete, and export PII.
• There is no rotation path, so a leak means a weekend of archaeology.

Treat a key like a password for a robot. Store it in a secret manager or an env file that is not in the repo. Name an owner. Log which integration used it, not the key itself.

OAuth2 is several products wearing one name

Authorization code (a person clicks “Connect Shopify”) is for acting as a user or a shop. You get tokens, you must refresh, you must handle revoke. Apps that skip refresh kick operators out and look like outages.

Client credentials is OAuth for machines: no human, a client id and secret, an access token with a lifetime. This is the grant you want for a daemon if the vendor offers it. It is not the same as “the CEO logged in once.”

JWT bearer and signed requests show up in banking and enterprise APIs. Inspect claims in the browser with the JWT decoder. Do not paste production tokens into random websites. Check expiry, audience, and whether the token is a key-shaped blob you should never log.

OAuth fails in production when the only working path is Postman with a human session cookie.

Choose by who is present

If the vendor only offers a user OAuth flow, your “server integration” still needs a stored refresh token, encryption at rest, alerting on refresh failure, and a reconnect UI. That is scope. Count it with the API project estimator.

The token refresh stampede problem

In a distributed backend or multi-container deployment, OAuth token refresh introduces a notorious production failure: the thundering herd.

When an access token has a short lifetime (e.g., 15 or 60 minutes) and five concurrent background workers or serverless lambdas hit a 401 Unauthorized at the exact same second, all five processes immediately attempt to call the vendor's /oauth/token endpoint using the identical refresh token.

This triggers three distinct failure modes:

1. Refresh Token Revocation: Many enterprise providers (such as Salesforce, Google, and Auth0) enforce single-use refresh token rotation. The first worker succeeds and receives a new refresh token; the other four concurrent calls arrive with the now-invalidated token, causing the vendor to revoke the entire authorization grant permanently.
2. Rate-Limit Cascades: The token endpoint rate-limits your IP, preventing even legitimate renewals and taking down the entire background pipeline.
3. Stale Token Overwrites: The worker that finishes last overwrites the newly minted token in your cache or database with an older or failed response.

The architectural solution is a centralized token manager with distributed locking (such as a Redis mutex or database advisory lock) and proactive renewal:

• Refresh ahead of expiry: Trigger renewal when 20% of token lifetime remains, rather than waiting for an in-flight API call to return a 401 error.
• Mutual exclusion: Only one worker acquires the renewal lock; all other workers await the cached token or poll the shared memory store with a 200ms backoff.
• Grace windows: Maintain the prior access token for a 30-second transition window if the vendor supports overlap.

Secret storage hardening in production

Putting production keys into a plaintext .env file checked into a private GitHub repository is the number one cause of credential compromise in growing teams.

Adopt a tiered secrets hierarchy:

• Development: Local .env.local files strictly excluded via .gitignore. Provide automated dummy mocks or sandbox keys with zero production write access.
• Staging: Secrets injected via the deployment platform (Vercel environment variables, AWS Systems Manager Parameter Store, or Docker secrets) with isolated test credentials.
• Production: Encrypted at rest using a dedicated Key Management Service (AWS KMS, HashiCorp Vault, or Google Cloud Secret Manager). Access to production secrets should require Multi-Factor Authentication (MFA) and leave an immutable audit trail.

Never pass secrets as query parameters or command-line arguments, where they are captured in web server access logs, reverse proxy access traces, and operating system process tables (ps aux).

Least privilege and blast radius

A key that can only write shipments cannot empty the catalogue. An OAuth app that requested every scope will leak every scope. Ask the vendor for scoped credentials. If they cannot, isolate that vendor in its own integration user and IP allowlist if they offer one.

Clock skew kills JWT validation. NTP on the host is part of auth. See how to secure a Linux production server for the host baseline; auth bugs on an unpatched box are a combined incident.

Incident response: when a credential leaks

When an API key is accidentally committed or an OAuth client secret is exposed, panic leads to bad operational choices that cause hours of unnecessary downtime. Follow this 4-step containment sequence:

1. Issue the replacement first: Generate a secondary key in the vendor dashboard before revoking the compromised one (the dual-key window). Update your secrets manager and trigger a rolling deployment.
2. Verify live traffic: Monitor application logs to confirm that all outbound requests are successfully authenticating with the new credential.
3. Revoke the compromised credential: Deactivate the old key in the vendor portal and confirm that requests using the revoked key immediately receive a 401 or 403 status code.
4. Audit vendor access logs: Inspect the vendor's audit log for the duration of the exposure window. Verify whether anomalous endpoints were called, customer records were exported, or unauthorized webhooks were registered.

Access control and secrets hygiene for small teams covers the human and operational policies required to prevent leaks before they reach git history.

Palmate will not treat “the token is in a Slack pin” as a delivery. Auth is done when a second engineer can rotate a credential and the job still runs. Until then you have a demo that happens to use HTTPS.

Authoritative References & Standards

To cross-reference the engineering patterns and regulatory considerations described in this guide, consult the following authoritative industry documentation and RFC standards:

• IETF RFC 7231: Hypertext Transfer Protocol (HTTP/1.1) Semantics and Content — The foundational standard for HTTP request methods, idempotency, and status codes.
• OpenAPI Specification (OAS) — The standard machine-readable interface definition for RESTful APIs.
• IETF RFC 7519: JSON Web Token (JWT) — Industry specification for securely representing claims between parties.