Production readiness

Your OAuth server should meet these performance targets to ensure a smooth user experience and reliable API access. Monitor and track these metrics continuously. Plaid also monitors integration health to help identify and resolve performance issues. Meeting these targets significantly impacts conversion rates and user satisfaction.

Latency: Slow responses increase user drop-off rates. Sub-3.5 second responses keep users engaged.

Throughput: Connection volumes can spike during peak times. Insufficient throughput creates bottlenecks that cascade to downstream apps.

Uptime: Downtime blocks new connections and refresh flows. In payment use cases, even 30 minutes of downtime can lead to ACH failures and customer complaints.

Conversion rate: Low conversion indicates UX problems (confusing screens, slow responses) or technical issues (timeout errors, redirect failures).

Track these metrics continuously:

• P50, P95, P99 latency for each OAuth endpoint
• HTTP status code distribution (200, 400, 401, 500, 503)
• OAuth flow completion rate (authorization -> token exchange success)
• Token refresh success rate
• JWKS endpoint availability and latency

Set up alerts for:

• Latency P95 exceeding 3.5 seconds
• Error rate exceeding 2%
• Uptime dropping below 99.5%
• Throughput capacity issues

Plan for growth:

• Volume projections for traffic increases over time
• Peak load during traffic spikes
• Refresh traffic from background calls (can generate significant additional load)
• JWKS caching (Plaid caches for 24 hours, reducing load on that endpoint)

Test your infrastructure under load before going live. Use load-testing tools to simulate hundreds of concurrent OAuth flows and verify that performance holds up.

Test in Plaid's Sandbox environment before going to Production. Catching issues early saves headaches later.

Run through these flows to make sure your OAuth server handles both success and failure gracefully:

• Complete authorization flow from start to finish
• Token exchange succeeds
• Refresh token flow works
• JWKS validation passes

• User cancels during authentication
• Correct error code returned (access_denied)
• Proper redirect back to Plaid with state parameter

• Wrong client ID or client secret
• Correct 401 or 400 response with invalid_client error

• Authorization code used twice
• Authorization code expired (> 10 minutes old)
• Returns invalid_grant error

• Access token expires after expires_in seconds
• Refresh flow triggers automatically
• New tokens issued successfully

• ID token signature verified successfully
• kid matches published JWKS
• Invalid signatures rejected

• All error codes from the error handling section return correctly
• Error responses include appropriate HTTP status codes
• Optional error_description provides useful debugging info

Before going live, verify:

• All OAuth endpoints use HTTPS
• No HTTP fallback available
• Valid TLS certificates (not self-signed in Production)

• Exact match required (including trailing slashes)
• Case-sensitive comparison
• No wildcard or regex matching

• expires_in matches actual token lifetime
• Tokens actually expire when claimed
• Refresh tokens have a reasonable expiration (13+ months recommended)

• Set if using browser-based flows
• Access-Control-Allow-Origin configured correctly
• Preflight requests handled

• Returns valid JSON
• All required fields present
• Endpoint accessible without authentication

• Use Plaid's Sandbox environment to test without affecting Production data
• Test with multiple apps and user scenarios to verify that the universal token model works across different user flows
• Simulate network issues and timeouts to ensure graceful degradation
• Test token revocation to confirm disconnection flows work

Complete before going live:

• OAuth server in Production environment
• Discovery endpoint accessible
• JWKS endpoint published and accessible
• Production credentials issued to Plaid
• mTLS certificates configured

• All test scenarios pass in Sandbox
• Load testing complete (300+ TPS)
• Error handling verified
• Token expiration tested
• Refresh flow tested

• Latency monitoring enabled
• Error rate alerts configured
• Uptime monitoring in place
• Log aggregation working
• On-call rotation established

• Runbooks created for common issues
• Escalation paths documented
• Support contact information shared with Plaid
• Maintenance window procedures defined