Credentials

Facio has two related credential paths: provider credentials for model routing and generic credentials for tools, MCP servers, scripts, and external services.

Provider credentials

Provider credentials live under providers.name. The management API exposes provider state through /api/v1/credentials/providers, but it never returns raw values.

Provider API responses include fields such as hasValue, masked, supportsApiBase, requiresApiBase, requiresApiKey, isOauth, isLocal, and defaultApiBase.

Generic credential store

Generic secrets are stored outside the agent workspace in credentials.json under the data directory. The store is shared by agent tools, MCP, credential management, and redaction.

Valid keys look like environment variable names: GITHUB_TOKEN, POSTGRES_URL, LINEAR_API_KEY.

curl -X POST http://localhost:8900/api/v1/credentials \
  -H "Authorization: Bearer $FACIO_MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"key":"GITHUB_TOKEN","value":"ghp_..."}'

Placeholder linking

Use placeholders where a config needs the secret:

${credentials.GITHUB_TOKEN}

Facio resolves this only at the boundary where it is needed, such as MCP env, MCP headers, or file write operations that intentionally need a secret. The agent can refer to the placeholder without seeing the raw value.

Password fields

When the agent asks for a password through a human form, Facio stores the submitted value and replaces it in the result with a placeholder. This is how the agent can help configure an MCP server or provider without receiving the raw password.

Shell exposure

By default, shell commands receive no stored credentials. To inject a credential as an environment variable into the exec sandbox, expose it explicitly:

/credentials expose GITHUB_TOKEN
/credentials unexpose GITHUB_TOKEN

or via API:

curl -X PUT http://localhost:8900/api/v1/credentials/GITHUB_TOKEN/exposed \
  -H "Authorization: Bearer $FACIO_MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"exposed":true}'

Expose only keys needed by a CLI, and remove exposure after the workflow no longer needs it.