Credentials

Tasks that talk to external systems load credentials from a JSON file referenced by credentials_path. Different connectors use different formats — there is no single global schema — but the convention is uniform: a file path on disk, parsed at task initialisation, never logged.

Where credentials_path appears

The format details live on each task’s documentation page. This page covers what is shared.

Why files, not environment variables

Credentials live in JSON files for three reasons:

• Kubernetes secrets mount cleanly as files. kubectl create secret generic ... then mount at /etc/flowgen/credentials/... — no env-var indirection.
• Multiple credentials per task (e.g., bearer plus basic auth fallback) compose naturally as one JSON object.
• No accidental logging. Environment variables show up in process inspection, error reports, and log scrapes. File paths in config do not leak the secret content.

If you need to inject secrets at deploy time without writing them to disk, use a secrets-management sidecar (External Secrets, Vault Agent, Sealed Secrets) to materialise the JSON file at the configured path.

HTTP credentials

The most common shared format is HttpCredentials, used by http_endpoint, http_request, and similar tasks:

{
  "bearer_auth": "your-token-here"
}

Or basic auth:

{
  "basic_auth": {
    "username": "your-user",
    "password": "your-pass"
  }
}

Both fields are optional. If neither is set, no Authorization header is added.

Example — webhook with bearer auth

/etc/flowgen/credentials/webhook.json:

{
  "bearer_auth": "shh-my-secret"
}

/etc/flowgen/flows/secure-webhook.yaml:

flow:
  name: secure_webhook
  tasks:
    - http_endpoint:
        name: ingest
        endpoint: /events
        method: POST
        credentials_path: /etc/flowgen/credentials/webhook.json

Incoming requests must include Authorization: Bearer shh-my-secret. Anything else returns 401.

Worker-level fallback for HTTP

The HTTP server has a worker-level credentials path that webhooks can inherit:

worker:
  http_server:
    enabled: true
    credentials_path: /etc/flowgen/credentials/http.json

Individual http_endpoint tasks override the worker default by setting their own credentials_path. This is useful when most webhooks share the same shared-secret token but a few endpoints have stricter requirements.

User-level authentication is separate

credentials_path authenticates the task itself (e.g., the bearer token for incoming webhook requests). User-level authentication — JWT, OIDC, session tokens — happens via the worker’s auth configuration. See Authentication.

The two compose: a webhook can require a worker-level shared secret (via credentials_path) and a user-level JWT (via auth.required: true). Both checks must pass.

Connection pooling

Tasks that share the same credentials_path automatically share the same authenticated client. The runtime hashes credential fields to detect duplicates — no configuration needed.

For example, if three flows each have a salesforce_restapi_sobject task pointing at the same credentials file, the first task to initialise performs the OAuth handshake. The other two wait and reuse the same session. This avoids hammering external services with redundant login calls and respects rate limits (e.g., Salesforce OAuth).

The key fields used for deduplication depend on the task family:

Tasks with different identity fields get separate clients. Two MSSQL tasks with the same credentials but different max_connections do not share a pool.

Operational notes

• File permissions should be 0600 (read-write for the flowgen user only). Flowgen does not enforce this — the operator is responsible.
• Hot reload is not supported. Credentials are read once at task initialisation. To rotate, restart the worker (or use connector-specific token refresh, e.g., GCP service account auto-rotation).
• Errors at startup: if the file is missing or malformed, the task fails to initialise and the standard retry circuit breaker fires. After ~15 minutes the task gives up. Watch worker logs for Failed to read credentials or Failed to parse credentials messages.
• Never commit credential files to Git. Pair with git_sync carefully: sync flow YAML, but mount credentials separately via a Kubernetes secret.