Credentials · Daemon API

On this page

Provider credential metadata and config overrides

GET/agents/{id}/providers/{providerId}/credentials

Operation getAgentProviderCredentialsAuthBearer token

Metadata only; stored values never leave the daemon.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`providerId`required	string	Provider id in the agent config example: anthropic

Responses

Status Description Body

200 Metadata ProviderCredentialsResponse

agentIdrequired

string

Agent id

providerIdrequired string

credentialsrequired

map<string, CredentialMeta>

By credential key (e.g. apiKey)

7 fields of credentials

`purpose`required	string
`present`required	boolean
`storage`required	string \| null	One of `sealed`, `plain`, `password`, `null`
`sealed`required	boolean
`locked`required	boolean	Stored but not readable in this process
`length`required	integer \| null	null for crypto:* purposes and locked values
`code_access`required	boolean

providerConfig object

3 fields of providerConfig

defaultModel string

params array<object>

2 fields of params

`key`required	string
`value`required	string

requestDelayMs integer

Errors 401 · 403 · 404 · 500

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/providers/anthropic/credentials" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Store a provider API key in the agent

PUT/agents/{id}/providers/{providerId}/credential

Operation setAgentProviderCredentialAuthBearer token

Stored as provider:{providerId}:apiKey. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 credentials_locked: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send replace: true (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as credential_replaced; the response then has replaced: true). replace is refused for key material (crypto:*, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`providerId`required	string	Provider id in the agent config example: anthropic

Request bodyapplication/json · IdentityValueBody · required

Field	Type	Description
`value`required	string
`replace`	boolean	Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`.

Responses

Status Description Body

200 Stored ProviderCredentialWriteResponse

`agentId`required	string	Agent id
`providerId`required	string
`success`required	boolean	Value `true`
`replaced`	boolean

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Missing value, or `replace` on key material
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (`credentials_locked`): unlock the owner identity, or retry with `replace: true`. A legacy agent locked with a whole-file password answers 409 `credentials_locked` until POST /agents/{id}/identity/password/unlock
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X PUT "http://127.0.0.1:7385/agents/agent-1/providers/anthropic/credential" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"sk-…"}'

MCP credential metadata by package

GET/agents/{id}/mcp/credentials

Operation getAgentMcpCredentialsAuthBearer token

Metadata only.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`npmPackage`required	string	Package or server name example: @acme/mcp-server

Responses

Status Description Body

200 Metadata by env key McpCredentialsResponse

agentIdrequired

string

Agent id

npmPackagerequired string

credentialsrequired

map<string, CredentialMeta>

By env key

7 fields of credentials

`purpose`required	string
`present`required	boolean
`storage`required	string \| null	One of `sealed`, `plain`, `password`, `null`
`sealed`required	boolean
`locked`required	boolean	Stored but not readable in this process
`length`required	integer \| null	null for crypto:* purposes and locked values
`code_access`required	boolean

Errors 400 · 401 · 403 · 404 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/mcp/credentials?npmPackage=@acme/mcp-server" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Store an MCP credential

PUT/agents/{id}/mcp/credentials

Operation setAgentMcpCredentialAuthBearer token

Stored as mcp:{npmPackage}:{envKey}. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 credentials_locked: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send replace: true (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as credential_replaced; the response then has replaced: true). replace is refused for key material (crypto:*, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Request bodyapplication/json · McpCredentialBody · required

Field	Type	Description
`npmPackage`required	string	Package or server name the credential belongs to
`envKey`required	string
`value`required	string
`replace`	boolean	Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`.

Responses

Status Description Body

200 Stored McpCredentialWriteResponse

`agentId`required	string	Agent id
`npmPackage`required	string
`envKey`required	string
`success`required	boolean	Value `true`
`replaced`	boolean

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Missing field, or `replace` on key material
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (`credentials_locked`): unlock the owner identity, or retry with `replace: true`. A legacy agent locked with a whole-file password answers 409 `credentials_locked` until POST /agents/{id}/identity/password/unlock
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X PUT "http://127.0.0.1:7385/agents/agent-1/mcp/credentials" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "npmPackage": "@acme/mcp-server",
  "envKey": "ACME_TOKEN",
  "value": "…"
}'

Channel adapter credential metadata by type

GET/agents/{id}/adapters/credentials

Operation getAgentAdapterCredentialsAuthBearer token

Metadata only.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`adapterType`required	string	Adapter type example: telegram

Responses

Status Description Body

200 Metadata by env key AdapterCredentialsResponse

agentIdrequired

string

Agent id

adapterTyperequired string

credentialsrequired

map<string, CredentialMeta>

By env key

7 fields of credentials

`purpose`required	string
`present`required	boolean
`storage`required	string \| null	One of `sealed`, `plain`, `password`, `null`
`sealed`required	boolean
`locked`required	boolean	Stored but not readable in this process
`length`required	integer \| null	null for crypto:* purposes and locked values
`code_access`required	boolean

Errors 400 · 401 · 403 · 404 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/adapters/credentials?adapterType=telegram" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Store a channel adapter credential

PUT/agents/{id}/adapters/credentials

Operation setAgentAdapterCredentialAuthBearer token

Stored as adapter:{adapterType}:{envKey}. Values go in, never out. While the agent's credentials envelope is locked (or foreign) on this daemon the write is refused with 409 credentials_locked: a plain write would destroy a sealed value it cannot read, or store a new one unsealed. Unlock the owner identity first, or send replace: true (the owner's override: a locked sealed value is discarded unread, the new value stored plain and sealed once the envelope unlocks, logged as credential_replaced; the response then has replaced: true). replace is refused for key material (crypto:*, 400). A write to an agent locked by a legacy whole-file identity password answers 500 (unlock it with POST …/identity/password/unlock).

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Request bodyapplication/json · AdapterCredentialBody · required

Field	Type	Description
`adapterType`required	string
`envKey`required	string
`value`required	string
`replace`	boolean	Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs (`credential_replaced`). Without it such a write answers 409 `credentials_locked`.

Responses

Status Description Body

200 Stored AdapterCredentialWriteResponse

`agentId`required	string	Agent id
`adapterType`required	string
`envKey`required	string
`success`required	boolean	Value `true`
`replaced`	boolean

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Missing field, or `replace` on key material
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (`credentials_locked`): unlock the owner identity, or retry with `replace: true`. A legacy agent locked with a whole-file password answers 409 `credentials_locked` until POST /agents/{id}/identity/password/unlock
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X PUT "http://127.0.0.1:7385/agents/agent-1/adapters/credentials" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "adapterType": "telegram",
  "envKey": "TELEGRAM_BOT_TOKEN",
  "value": "…"
}'