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: 
{
  "version": 2,
  "amount": 1500.00
}
If two processes update the same resource concurrently, the second write returns HTTP 409 Conflict: 
{
  "success": false,
  "errors": [{
    "code": "OPTIMISTIC_LOCK_EXCEPTION",
    "message": "The resource has been modified. Please fetch the latest version and retry."
  }]
}
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: 
{
  "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "...": "other fields"
}
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. 
# Staging
TOKEN_URL=https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token
FUNDFLOW_BASE_URL=https://api-fundflow-staging.venly.io/v1
FINANCE_BASE_URL=https://api-staging.venlyfinance.com/v1

# Production
TOKEN_URL=https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token
FUNDFLOW_BASE_URL=https://api-fundflow.venly.io/v1
FINANCE_BASE_URL=https://api.venlyfinance.com/v1

​
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