Skip to main content

​
Credentials

Your Client ID and Client Secret are the root of access to both APIs. Treat them like passwords.
Never hard-code credentials in source code, commit them to version control, or include them in client-side bundles. A leaked secret provides full API access under your account.
Do:
  • Store credentials in environment variables (CLIENT_ID, CLIENT_SECRET)
  • Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) in production
  • Rotate secrets on a regular schedule and immediately if a leak is suspected
  • Use separate credentials for staging and production
Don’t:
  • Log credential values anywhere
  • Pass secrets through URL query parameters
  • Share credentials between team members — provision individual service accounts where possible

​
Token Security

Access tokens are short-lived (5 minutes) Bearer tokens. They are equivalent to session credentials.
  • Never log token values — they grant full API access for their lifetime
  • Do not store tokens persistently (database, disk) — request a fresh one as needed
  • After a 401 Unauthorized response, re-authenticate once and retry; do not retry indefinitely
  • Use HTTPS on all requests — tokens sent over plain HTTP can be intercepted

​
Transport Security

All API and token endpoint traffic must use HTTPS. The endpoints enforce TLS — plain HTTP connections are rejected. Verify your HTTP client does not disable certificate validation. Disabling it (e.g. verify=False in Python requests) exposes you to man-in-the-middle attacks in production.

​
Optimistic Locking

Fundflow uses optimistic locking to prevent race conditions on shared resources. Every mutable resource carries a version integer. Include the current version on all update requests:
If two processes update the same resource concurrently, the second write returns HTTP 409 Conflict:
On a 409, fetch the resource again to get the latest version, apply your changes, and retry.

​
Idempotency (Finance API)

Relevant Finance API endpoints accept an idempotencyKey field in the request body — a UUID you generate per request:
Use a fresh UUID for each new logical operation. On a network failure, retry with the same key — the API returns the original response without creating a duplicate. Re-using a key with a different request body returns HTTP 422.

​
Environment Isolation

Never mix staging and production credentials or base URLs. Maintain separate configuration for each environment and gate the switch explicitly — do not infer the environment from other runtime state.

​
Audit Logging

Log the following for every API call your system makes:
  • Timestamp
  • HTTP method and path (no query strings containing sensitive data)
  • HTTP status code
  • Request ID from the response (if present)
  • Duration
Do not log request bodies containing credentials, tokens, or PII.

​
Reporting Security Issues

Contact: venlyfinance.com/contact — response within 2 hours for security issues.

Troubleshooting

API error codes and common fixes

Authentication

Token management and refresh patterns