Owner identity
The owner identity on this machine (seed phrase, keychain or passphrase file). State-changing routes are loopback only.
On this page
Owner identity status (no secrets)
/identityThe 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
runtimeobject | Whose runtime identity the daemon uses. 6 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
staterequired | string | |
sourcerequired | string | |
reasonrequired | string | null | |
daemonRuntimeDidrequired | string | null | The daemon's own runtime DID |
daemonEncPublicKeyrequired | string | null | Base64 raw X25519 public key of the daemon's runtime-enc-key (what Studio lists in trustedDaemonEncKeys) |
messagerequired | string | One sentence for the UI |
storagerequiredbackupConfirmedrequiredpassphraseRequiredrequiredFile storage not unlocked: create/restore/unlock take a passphrase
keychainProblemThe daemon could not read this machine's OS keychain at start and runs on its passphrase file: why and what to do; null otherwise. Create, restore, import and trust-daemon answer 409 keychain_unavailable meanwhile (set ADF_SECRET_STORE=file to use the file on purpose).
messagerequiredWhat 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
curl "http://127.0.0.1:7385/identity" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"status": "ready",
"ownerDid": "did:key:z6MkOwner…",
"runtimeDid": "did:key:z6MkRuntime…",
"runtime": {
"state": "adopted",
"source": "studio",
"reason": null,
"daemonRuntimeDid": null,
"daemonEncPublicKey": "q9Jw…=",
"message": "Using ADF Studio's runtime identity did:key:z6MkRuntime… from the OS keychain, so agents open and unlock as they do in Studio."
},
"storage": "keychain",
"backupConfirmed": true,
"passphraseRequired": false,
"message": "Owner identity is ready."
}Create the owner identity; returns the seed phrase ONCE (loopback only)
/identity/createOnly 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 |
Request bodyapplication/json · IdentityPassphraseBody · optional
| Field | Type | Description |
|---|---|---|
passphrase | string | Required with file storage (no OS keychain) |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | Created. Show the phrase once; it is never returned again. | IdentityCreateResponse | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 409 · 500 · 503
| 400 | No keychain and no/weak passphrase (passphrase_required, weak_passphrase) | IdentityErrorResponse | ||||||
| ||||||||
| 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 | ||||||
| ||||||||
| 500 | Unexpected runtime failure | |||||||
| 503 | The subsystem is not configured on this daemon | |||||||
Error bodies use the error format.
Example
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)
/identity/restoreA 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 |
Request bodyapplication/json · IdentityRestoreBody · required
| Field | Type | Description |
|---|---|---|
mnemonicrequired | string | 12-word BIP-39 phrase (case/whitespace-insensitive) |
passphrase | string |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | Restored | IdentityStatusEnvelope | |||
| |||||
Errors 400 · 401 · 403 · 409 · 500 · 503
| 400 | Invalid phrase or passphrase (invalid_mnemonic, passphrase_required, weak_passphrase) | IdentityErrorResponse | ||||||
| ||||||||
| 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 | ||||||
| ||||||||
| 500 | Unexpected runtime failure | |||||||
| 503 | The subsystem is not configured on this daemon | |||||||
Error bodies use the error format.
Example
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"}'Trust this daemon's key (owner action, no OS keychain)
/identity/trust-daemonK12. Adds the daemon's key (runtime-enc-key) to trustedDaemonEncKeys, so ADF Studio wraps every agent's credentials to it and they unlock here without the owner passphrase; loaded agents get their slot at once. An explicit owner action, never automatic: the body must say confirm: true. Refused when the daemon reads the OS keychain (keychain_available) and without the owner key (not_ready). The grant is a settings entry, not a signed statement. Local callers only, always with the local proof (see Local-only routes).
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
confirmrequired | boolean |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The trust state after the call, and how many loaded agents got or lost their slot | object | ||||||||||||||||||
agentsUpdatedrequiredinteger | | |||||||||||||||||||
Errors 400 · 401 · 403 · 409 · 503
| 400 | No confirm: true (confirm_required); the error says what trusting means | IdentityErrorResponse | ||||||
| ||||||||
| 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 | The daemon reads the OS keychain (keychain_available) or the owner key is not available (not_ready) | IdentityErrorResponse | ||||||
| ||||||||
| 503 | No owner identity service on this daemon | |||||||
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/identity/trust-daemon" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"confirm":true}'Revoke the owner's trust in this daemon's key
/identity/untrust-daemonK12. Removes the daemon's key from trustedDaemonEncKeys and rotates it: a new key replaces the key file, the old one is no longer used, and its label is recorded as revoked. Loaded agents lose the slot at once, agents in the tracked folders in a background sweep (sweep: started; it skips files another runtime runs and documents this daemon holds open, which are cleaned when next opened), any other agent when this daemon or ADF Studio next opens it. A copy outside the tracked folders keeps the old slot until it is opened; anyone holding a copy of the old key file can open that slot until then. Slots of the daemon's own runtime wrapped to the old key open again after the next owner-key unlock. The daemon never adds a key back by itself. Local callers only, always with the local proof.
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The trust state after the call, and how many loaded agents got or lost their slot | object | ||||||||||||||||||
agentsUpdatedrequiredinteger | | |||||||||||||||||||
Errors 401 · 403 · 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 | |
| 503 | No owner identity service on this daemon |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/identity/untrust-daemon" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Unlock a passphrase-file identity (loopback only)
/identity/unlockOnly 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 |
Request bodyapplication/json · IdentityPassphraseBody · required
| Field | Type | Description |
|---|---|---|
passphrase | string | Required with file storage (no OS keychain) |
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 | ||||||
| ||||||||
| 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 | ||||||
| ||||||||
| 500 | Unexpected runtime failure | |||||||
| 503 | The subsystem is not configured on this daemon | |||||||
Error bodies use the error format.
Example
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)
/identity/lockNo 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 |
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 | ||||||
| ||||||||
| 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
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)
/identity/confirm-backupNo 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 |
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 | ||||||
| ||||||||
| 500 | Unexpected runtime failure | |||||||
| 503 | The subsystem is not configured on this daemon | |||||||
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/identity/confirm-backup" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Import an owner seed phrase, switching owners when confirmed (loopback only)
/identity/importStudio's Import identity. The phrase of this machine's owner acts as a restore. The phrase of another owner answers 409 switch_unconfirmed, naming both DIDs, unless switchOwner is true; then that owner replaces this machine's owner and the agents of the previous owner in tracked directories are restamped, except files another runtime runs (restamp.skipped; restamped when next opened). Loaded agents are unloaded before the restamp and loaded again after it; the response lists both. A Studio runtime identity the daemon had adopted is re-certified by the new owner on a switch, and the daemon rewrites its OS keychain entry (same keys, new delegation), so identity.runtime.state stays adopted and agents made in Studio keep unlocking without Studio running. Unlike the other local-only routes, this one always requires X-ADF-Local-Proof (the daemon writes the proof file on every run), not only in proxy mode. Every refusal (phrase, confirmations, file-storage passphrase) happens before an agent is unloaded; imports run one at a time. On a switch the daemon also moves ADF Studio's stored copy of the previous phrase, still encrypted, from ownerMnemonic to ownerMnemonicSuperseded:<previous owner DID> in the settings file, so Studio takes the new phrase from the OS keychain at its next start. The phrase never appears in a response, log or error. Local callers only (see Local-only routes).
Header parameters
| Name | Type | Description |
|---|---|---|
X-ADF-Local-Proof | string | Required only when the daemon runs with |
Request bodyapplication/json · IdentityImportBody · required
| Field | Type | Description |
|---|---|---|
mnemonicrequired | string | 12-word BIP-39 phrase (case/whitespace-insensitive) |
passphrase | string | File storage only, when it is not unlocked |
switchOwner | boolean | Required (true) when the phrase belongs to another owner than this machine's |
previousOwnerBackupConfirmed | boolean | The caller holds the previous owner's phrase although its backup was never confirmed ( |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Imported | IdentityImportResponse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reloadedrequiredarray<object> | 3 fields of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
agentIdrequired | string | |
namerequired | string | |
filePathrequired | string |
reloadFailuresrequired3 fields of reloadFailures
namerequired | string | |
filePathrequired | string | |
errorrequired | string |
Errors 400 · 401 · 403 · 409 · 500 · 503
| 400 | Invalid phrase, passphrase or field type (invalid_mnemonic, passphrase_required, weak_passphrase, bad_request) | IdentityErrorResponse | ||||||
| ||||||||
| 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 | The phrase belongs to another owner and switchOwner is not true (switch_unconfirmed), or the previous owner's backup is unconfirmed and previousOwnerBackupConfirmed is not true (backup_unconfirmed; the switch overwrites the daemon's copy of that phrase), or ADF Studio runs agents in embedded mode on the same settings file (studio_running, naming its pid and the file: quit it or import in Studio; checked first, from the runtime host registry) | IdentityErrorResponse | ||||||
| ||||||||
| 500 | Unexpected runtime failure | |||||||
| 503 | The subsystem is not configured on this daemon | |||||||
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/identity/import" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"mnemonic":"string"}'Mint an identity draft
/identity/draftsA keypair held in daemon memory (30 min, at most 16) so a create screen can show the next agent’s DID; creating with its draftId adopts it.
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | OK | IdentityDraft | ||||||
| ||||||||
Errors 401 · 403
| 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 |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/identity/drafts" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Discard an identity draft
/identity/drafts/{draftId}Path parameters
| Name | Type | Description |
|---|---|---|
draftIdrequired | string | Draft id |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | OK | IdentityDraftDiscardResponse | |||
| |||||
Errors 401 · 403
| 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 |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/identity/drafts/DRAFT_ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"