Skip to main content

Security Best Practices

Follow these guidelines to keep your integration secure.

1. Protect your private key​

Your private key is the most sensitive part of this integration. If compromised, an attacker can impersonate your application.

  • Store it in a secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) or HSM.
  • Never commit it to source control.
  • Never embed it in client-side code (browsers, mobile apps).
  • Never transmit it over the network.
  • Restrict file system permissions to only the application user.

2. Use short-lived assertions​

Set exp to 2-5 minutes after iat. There is no benefit to longer-lived assertions since they are single-use. Shorter lifetimes reduce the window of exposure if an assertion is intercepted.

3. Always use a unique jti​

Use a UUID v4 for each assertion. Every single token exchange request must have a different jti. Reusing a jti will be rejected as a replay attack.

4. Rotate your keys periodically​

Regular key rotation limits the impact of a compromised key:

  1. Generate a new ECDSA key pair.
  2. Register the new public key in the Partner Portal.
  3. Update your application to use the new private key and API Key ID.
  4. Verify the new key works.
  5. Delete the old key from the Partner Portal.
tip

Keep both keys active during the transition period. Only delete the old key after your application has fully migrated.

5. Request only the scopes you need​

Use the scope parameter to limit your token's permissions. If you only need read access, request partner.read only. This follows the principle of least privilege and limits damage if a token is compromised.

6. Refresh tokens proactively​

Don't wait for a 401 Unauthorized response. Track the expiresIn value and refresh your token before it expires (e.g., at the 50-minute mark). This avoids failed requests and provides a smoother experience.

7. Keep your server clock accurate​

JWT validation checks iat and exp timestamps. RynoPay allows a 30-second clock skew, but significant drift can cause authentication failures. Use NTP to keep your server time synchronised.

8. Use TLS for all API calls​

All RynoPay endpoints require HTTPS. Never send tokens or assertions over unencrypted HTTP connections.

9. Handle tokens securely in memory​

  • Don't log access tokens or assertions.
  • Don't store tokens in databases or files -- keep them in memory only.
  • Clear tokens from memory when they are no longer needed.

10. Monitor your API key usage​

Regularly check the "Last Used" timestamp for your API keys in the Partner Portal. If you see unexpected activity, rotate your keys immediately and contact RynoPay support.