Owner identity · Daemon API

Owner identity status (no secrets)

GET/identity

Operation getOwnerIdentityAuthBearer token

The owner identity (a DID derived from a 12-word BIP-39 phrase) is what new agents are sealed and attested under, the same identity ADF Studio uses. Stored in the OS keychain (shared with Studio), or where there is none in a passphrase-encrypted owner-secrets.json next to the daemon settings. status: none (create or restore), locked (unlock), restore-needed (this machine has an owner DID, e.g. from Studio, but the daemon lacks its phrase: restore), ready. passphraseRequired: true means file storage. Whenever the identity becomes ready the daemon re-unlocks every loaded agent that is degraded (credentials locked), without a reload.

Responses

Status Description Body

200 Status IdentityStatus

`status`required	string	One of `none`, `locked`, `restore-needed`, `ready`
`ownerDid`required	string \| null
`runtimeDid`required	string \| null	This daemon's own runtime DID (never Studio's)
`storage`required	string	One of `keychain`, `file`
`backupConfirmed`required	boolean
`passphraseRequired`required	boolean	File storage not unlocked: create/restore/unlock take a passphrase
`message`required	string	What to do next

Errors 401 · 403 · 500 · 503

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`
500	Unexpected runtime failure
503	The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

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

Response 200

{
  "status": "ready",
  "ownerDid": "did:key:z6MkOwner…",
  "runtimeDid": "did:key:z6MkRuntime…",
  "storage": "keychain",
  "backupConfirmed": true,
  "passphraseRequired": false,
  "message": "Owner identity is ready."
}

Create the owner identity; returns the seed phrase ONCE (loopback only)

POST/identity/create

Operation createOwnerIdentityAuthBearer tokenLoopback only

Only when status is none. passphrase (8+ characters) is required with file storage. Show the words to the user once, then call POST /identity/confirm-backup. Local callers only (see Local-only routes).

Header parameters

Name	Type	Description
`X-ADF-Local-Proof`	string	Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `<settings dir>/daemon-local-proof` (`daemon-local-proof-<port>` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Request bodyapplication/json · IdentityPassphraseBody · optional

Field	Type	Description
`passphrase`	string	Required with file storage (no OS keychain) length: ≥ 8

Responses

Status Description Body

201 Created. Show the phrase once; it is never returned again. IdentityCreateResponse

`mnemonic`required	string
`words`required	array<string>	items: 12–12
`identity`required	object	Fields as in IdentityStatus above.

Errors 400 · 401 · 403 · 409 · 500 · 503

400 No keychain and no/weak passphrase (passphrase_required, weak_passphrase) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

401 Missing or wrong bearer token (unauthorized)

403 Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin

409 An identity already exists (identity_exists, owner_mismatch) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/identity/create" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Restore the owner identity from its seed phrase (loopback only)

POST/identity/restore

Operation restoreOwnerIdentityAuthBearer tokenLoopback only

A phrase of a different owner than the one this machine already has answers 409 owner_mismatch (switch owners in Studio instead); a wrong passphrase for an existing file 403 wrong_passphrase. Local callers only (see Local-only routes).

Header parameters

Name	Type	Description
`X-ADF-Local-Proof`	string	Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `<settings dir>/daemon-local-proof` (`daemon-local-proof-<port>` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Request bodyapplication/json · IdentityRestoreBody · required

Field	Type	Description
`mnemonic`required	string	12-word BIP-39 phrase (case/whitespace-insensitive)
`passphrase`	string

Responses

Status Description Body

200 Restored IdentityStatusEnvelope

identityrequired

object

Fields as in IdentityStatus above.

Errors 400 · 401 · 403 · 409 · 500 · 503

400 Invalid phrase or passphrase (invalid_mnemonic, passphrase_required, weak_passphrase) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

401 Missing or wrong bearer token (unauthorized)

403 Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin

409 A different owner is already set up here (owner_mismatch, identity_exists) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/identity/restore" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mnemonic":"string"}'

Unlock a passphrase-file identity (loopback only)

POST/identity/unlock

Operation unlockOwnerIdentityAuthBearer tokenLoopback only

Only for file storage (no OS keychain). A wrong passphrase answers 403 wrong_passphrase. The daemon can also unlock at boot from ADF_OWNER_PASSPHRASE or ADF_OWNER_PASSPHRASE_FILE. Local callers only (see Local-only routes).

Header parameters

Name	Type	Description
`X-ADF-Local-Proof`	string	Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `<settings dir>/daemon-local-proof` (`daemon-local-proof-<port>` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Request bodyapplication/json · IdentityPassphraseBody · required

Field	Type	Description
`passphrase`	string	Required with file storage (no OS keychain) length: ≥ 8

Responses

Status	Description	Body
200	Unlocked	IdentityStatusEnvelope
Fields as in IdentityStatusEnvelope above.

Errors 400 · 401 · 403 · 409 · 500 · 503

400 Keychain storage (not_file_storage) or no passphrase (passphrase_required) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

401 Missing or wrong bearer token (unauthorized)

403 Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin

409 No identity file yet (nothing_to_unlock) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/identity/unlock" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Lock a passphrase-file identity (loopback only)

POST/identity/lock

Operation lockOwnerIdentityAuthBearer tokenLoopback only

No body. Local callers only (see Local-only routes).

Header parameters

Name	Type	Description
`X-ADF-Local-Proof`	string	Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `<settings dir>/daemon-local-proof` (`daemon-local-proof-<port>` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Responses

Status	Description	Body
200	Locked	IdentityStatusEnvelope
Fields as in IdentityStatusEnvelope above.

Errors 400 · 401 · 403 · 500 · 503

400 Keychain storage cannot be locked by the daemon (not_file_storage) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

401 Missing or wrong bearer token (unauthorized)

403 Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/identity/lock" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Record that the seed phrase was written down (loopback only)

POST/identity/confirm-backup

Operation confirmOwnerBackupAuthBearer tokenLoopback only

No body. Local callers only (see Local-only routes).

Header parameters

Name	Type	Description
`X-ADF-Local-Proof`	string	Required only when the daemon runs with `ADF_DAEMON_BEHIND_PROXY`: the contents of `<settings dir>/daemon-local-proof` (`daemon-local-proof-<port>` off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Responses

Status	Description	Body
200	Confirmed	IdentityStatusEnvelope
Fields as in IdentityStatusEnvelope above.

Errors 401 · 403 · 409 · 500 · 503

401 Missing or wrong bearer token (unauthorized)

403 Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin

409 No usable identity (not_ready) IdentityErrorResponse

`error`required	string
`code`required	string	One of `invalid_mnemonic`, `owner_mismatch`, `identity_exists`, `passphrase_required`, `weak_passphrase`, `wrong_passphrase`, `not_file_storage`, `nothing_to_unlock`, `not_ready`, `loopback_only`

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/identity/confirm-backup" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"