Identity (agent) · Daemon API

On this page

List stored identity entries (no values)

GET/agents/{id}/identities

Operation getAgentIdentitiesAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Entries IdentityListResponse

agentIdrequired

string

Agent id

identitiesrequired array<object>

3 fields of identities

`purpose`required	string
`encrypted`required	boolean
`code_access`required	boolean

Errors 401 · 403 · 404

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, …)

Error bodies use the error format.

Example

Request

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

List identity purposes

GET/agents/{id}/identity

Operation listAgentIdentityPurposesAuthBearer token

Path parameters

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

Query parameters

Name	Type	Description
`prefix`	string	Only purposes starting with this

Responses

Status Description Body

200 Purposes IdentityPurposesResponse

`agentId`required	string	Agent id
`purposes`required	array<string>

Errors 401 · 403 · 404

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, …)

Error bodies use the error format.

Example

Request

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

List stored identity entries (alias of …/identities)

GET/agents/{id}/identity/entries

Operation listAgentIdentityEntriesAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Entries IdentityListResponse

agentIdrequired

string

Agent id

identitiesrequired array<object>

3 fields of identities

`purpose`required	string
`encrypted`required	boolean
`code_access`required	boolean

Errors 401 · 403 · 404

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, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/identity/entries" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Whether the identity store has a password and is unlocked

GET/agents/{id}/identity/password

Operation getAgentIdentityPasswordStatusAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Status IdentityPasswordStatus

`agentId`required	string	Agent id
`needsPassword`required	boolean
`unlocked`required	boolean

Errors 401 · 403 · 404

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, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/identity/password" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Set an identity password (legacy whole-file encryption)

PUT/agents/{id}/identity/password

Operation setAgentIdentityPasswordAuthBearer token

Always 400 not_supported: whole-file passwords are no longer supported.

Path parameters

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

Request bodyapplication/json · IdentityPasswordBody · required

Field	Type	Description
`password`required	string

Responses

Status Description Body

200 Set AgentSuccess

`agentId`required	string	Agent id
`success`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 -X PUT "http://127.0.0.1:7385/agents/agent-1/identity/password" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"string"}'

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Remove the identity password

DELETE/agents/{id}/identity/password

Operation removeAgentIdentityPasswordAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Removed AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

Errors 401 · 403 · 404 · 409 · 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, …)
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 DELETE "http://127.0.0.1:7385/agents/agent-1/identity/password" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Unlock a password-protected identity store

POST/agents/{id}/identity/password/unlock

Operation unlockAgentIdentityPasswordAuthBearer token

Path parameters

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

Request bodyapplication/json · IdentityPasswordBody · required

Field	Type	Description
`password`required	string

Responses

Status Description Body

200 Unlocked AgentSuccess

`agentId`required	string	Agent id
`success`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 -X POST "http://127.0.0.1:7385/agents/agent-1/identity/password/unlock" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"string"}'

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Change the identity password

POST/agents/{id}/identity/password/change

Operation changeAgentIdentityPasswordAuthBearer token

Always 400 not_supported: whole-file passwords are no longer supported.

Path parameters

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

Request bodyapplication/json · IdentityChangePasswordBody · required

Field	Type	Description
`newPassword`required	string	Alias: new_password

Responses

Status Description Body

200 Changed AgentSuccess

`agentId`required	string	Agent id
`success`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 -X POST "http://127.0.0.1:7385/agents/agent-1/identity/password/change" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newPassword":"string"}'

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

The agent's DID

GET/agents/{id}/identity/did

Operation getAgentDidAuthBearer token

Path parameters

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

Responses

Status Description Body

200 DID (null when no keys) AgentDidResponse

`agentId`required	string	Agent id
`did`required	string \| null

Errors 401 · 403 · 404

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, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/identity/did" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "did": "did:key:z6Mk…"
}

Generate the agent's signing keys

POST/agents/{id}/identity/generate-keys

Operation generateAgentIdentityKeysAuthBearer token

No body.

Path parameters

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

Responses

Status Description Body

200 Generated GenerateKeysResponse

`agentId`required	string	Agent id
`success`required	boolean	Value `true`
`did`required	string

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 -X POST "http://127.0.0.1:7385/agents/agent-1/identity/generate-keys" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Wipe every identity row

POST/agents/{id}/identity/wipe

Operation wipeAgentIdentityAuthBearer token

Irreversible: keys, DID and every stored credential go. No body.

Path parameters

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

Responses

Status Description Body

200 Wiped AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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 -X POST "http://127.0.0.1:7385/agents/agent-1/identity/wipe" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Delete identity values by purpose prefix

DELETE/agents/{id}/identity-prefix

Operation deleteAgentIdentityPrefixAuthBearer token

Path parameters

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

Query parameters

Name	Type	Description
`prefix`required	string	Purpose prefix, e.g. `mcp:@acme/server:`

Responses

Status Description Body

200 Deleted count IdentityPrefixDeleteResponse

`agentId`required	string	Agent id
`prefix`required	string
`deleted`required	integer

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 -X DELETE "http://127.0.0.1:7385/agents/agent-1/identity-prefix?prefix=PREFIX" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Metadata of one stored value (never the value)

GET/agents/{id}/identity/{purpose}

Operation getAgentIdentityValueAuthBearer token

Values and key material (crypto:signing:*, crypto:envelope:*, owner/runtime keys) never leave the daemon by any route. storage: sealed (envelope-encrypted), plain, password (legacy whole-file password) or null (absent); locked: stored but unreadable in this process; length is null for crypto:* and locked values.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`purpose`required	string	Identity purpose, e.g. `provider:anthropic:apiKey`

Responses

Status Description Body

200 Metadata AgentIdentityMetaResponse

`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
`agentId`required	string

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/identity/PURPOSE" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Store one identity value

PUT/agents/{id}/identity/{purpose}

Operation setAgentIdentityValueAuthBearer token

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
`purpose`required	string	Identity purpose, e.g. `provider:anthropic:apiKey`

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 IdentityWriteResponse

`agentId`required	string	Agent id
`purpose`required	string
`success`required	boolean	Value `true`
`replaced`	boolean	A locked sealed value was discarded (replace: true)

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/identity/PURPOSE" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"sk-…"}'

Delete one identity value

DELETE/agents/{id}/identity/{purpose}

Operation deleteAgentIdentityValueAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`purpose`required	string	Identity purpose, e.g. `provider:anthropic:apiKey`

Responses

Status Description Body

200 success is false when nothing was deleted IdentityDeleteResponse

`agentId`required	string	Agent id
`purpose`required	string
`success`required	boolean

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 -X DELETE "http://127.0.0.1:7385/agents/agent-1/identity/PURPOSE" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Allow or deny code (sys_code / lambdas) reading a value

PATCH/agents/{id}/identity/{purpose}/code-access

Operation setAgentIdentityCodeAccessAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`purpose`required	string	Identity purpose, e.g. `provider:anthropic:apiKey`

Request bodyapplication/json · IdentityCodeAccessBody · required

Field	Type	Description
`codeAccess`required	boolean	Alias: code_access

Responses

Status Description Body

200 Saved IdentityDeleteResponse

`agentId`required	string	Agent id
`purpose`required	string
`success`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 -X PATCH "http://127.0.0.1:7385/agents/agent-1/identity/PURPOSE/code-access" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"codeAccess":true}'