Security best practices

Allowlist Plaid's IP addresses in your firewall, WAF, or security vendor configuration to prevent legitimate API traffic from being blocked. This ensures scheduled balance and transaction updates run smoothly.

Add these IP addresses:

• 162.120.88.0/22
• 2602:F74B::/40

If already present, do not remove:

• 18.214.218.91
• 3.211.30.208
• 3.214.25.67
• 54.88.74.128
• 54.208.59.10
• 54.88.202.28

Implementation:

• Notify your Plaid contact once allowlisting is complete.
• Allowlisting does not bypass authentication. Users still complete login and MFA on first connection.
• Scheduled refreshes can proceed without repeated MFA challenges.

Core Exchange implements security in layers. Each layer reinforces the others:

• Transport: TLS 1.2+, mTLS for Production
• Authentication: Client credentials, token-based access
• Authorization: Scoped tokens, user consent
• Validation: JWKS signature verification, PKCE
• Lifecycle: Token expiration, refresh rotation, key rotation

Defense in depth: If one layer is compromised, the others still protect the system.

Implement these high-impact practices first:

• Use HTTPS everywhere - All OAuth endpoints must use HTTPS with valid certificates. Plaid validates TLS and blocks self-signed certificates in Production.
• Expire access tokens in 15 min - Plaid automatically refreshes expired tokens. If you expire a token early, return a 401 with error code "602 not authorized".

• Enable mTLS in Production - Mutual authentication prevents client impersonation. Coordinate with your Plaid contact to configure.
• Use PKCE for mobile - Prevents authorization code interception on public clients. Include code_challenge and code_challenge_method parameters.
• Rotate keys annually - Or immediately if compromised. Schedule during low-traffic periods. Plaid caches JWKS for 24 hours.
• Encrypt client secrets - Never store in plain text. Use secrets manager or vault.

These six practices address 80% of common security risks. Then implement the complete checklist below.

All OAuth endpoints must use TLS 1.2 or higher. Sandbox environments accept self-signed certificates, but Production requires CA-signed certificates.

Many Data Providers require mutual TLS for server-to-server token endpoint calls. This adds certificate-based authentication on top of client credentials, providing an additional security layer.

When you use mTLS:

• Plaid presents a client certificate during the TLS handshake.
• Your server validates the certificate against a trust store.
• The certificate identifies Plaid as the connecting client.

Certificate management:

1. Plaid initiates rotation - Plaid monitors certificate expiration and notifies you at least 2 weeks before expiration
2. Generate a new certificate - Plaid generates a new certificate with updated expiration and provides it to you
3. Update trust store - Add new certificate to your trust store (keep old cert active during transition)
4. Testing window - Allow 48-72 hours for testing with the new certificate
5. Remove old certificate - After confirming success, remove the expired certificate from the trust store

Best practices:

• Set up alerts 30 days before certificate expiration.
• Test certificate rotation in Sandbox before Production.
• Maintain both old and new certificates during the transition period.
• Document certificate details (CN, expiration, issuer) for reference.

Encrypt at rest - Never store client secrets in plaintext. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) or, at a minimum, encrypt them in your database.

Secure generation - Use a cryptographically secure pseudo-random number generator (CSPRNG) for all secrets. Don't use UUIDs or predictable values.

Short-lived access tokens - 15 minutes (900 seconds) is short enough to limit exposure, long enough to avoid excessive refresh calls.

Refresh token rotation - Issue new refresh tokens with each use. This limits the window if a refresh token is compromised.

Revocation support - Build a way to revoke tokens when users disconnect or when you detect suspicious activity.

Use S256 - If you support public clients (mobile apps, SPAs), require PKCE with the S256 challenge method. This prevents authorization code interception attacks.

Annual minimum - Rotate JWKS signing keys at least once a year.

Emergency rotation - Have a process ready to rotate keys immediately if a key is compromised. Test it before you need it.

Grace period - When rotating keys, publish new keys before removing old ones. Give Plaid time to cache the new keys (typically 24 hours).

Track key usage - Include a unique kid (Key ID) in every key so you can identify which key signed which token.

• Use openid + offline_access scopes - See OAuth Server Setup
• Log state, userId, and timestamps for every session - See Troubleshooting
• Monitor OAuth and JWKS validation success rates - See Troubleshooting and Production Readiness

Initial implementation: Complete full security review before Production launch

Ongoing:

• Quarterly: Review access logs, error patterns, and credential rotation schedule.
• Annually: Rotate JWKS keys, review TLS configuration, and update dependencies.
• After incidents: Review immediately if a security event is detected.

• HTTPS on all OAuth endpoints with valid CA certificates
• Access tokens expire in 15 minutes
• Refresh tokens expire in 13+ months (or rotate on each use)
• mTLS configured for Production (if required)
• PKCE enabled for mobile/public clients
• Client secrets encrypted at rest
• JWKS key rotation process documented and tested
• Certificate rotation process documented and tested
• Security review schedule established