> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & Best Practices

> Credential management, token security, and defensive patterns for Fundflow API integrations

## Credentials

Your **Client ID** and **Client Secret** are the root of access to both APIs. Treat them like passwords.

<Warning>
  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.
</Warning>

**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:

```json theme={null}
{
  "version": 2,
  "amount": 1500.00
}
```

If two processes update the same resource concurrently, the second write returns **HTTP 409 Conflict**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```bash theme={null}
# 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](https://venlyfinance.com/contact) — response within 2 hours for security issues.

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/guides/payments/troubleshooting">
    API error codes and common fixes
  </Card>

  <Card title="Authentication" icon="key" href="/guides/payments/authentication">
    Token management and refresh patterns
  </Card>
</CardGroup>