Auth: Device-signed read, operation device-log-read.
Request and response
Angle-bracket values describe placeholders, including nested objects and numeric types; these are wire shapes, not captured service data. Replace them before sending.
POST /v1/devices/log HTTP/1.1
Host: trust-staging.rebellion.systems
Content-Type: application/json
{
"graphNodeId": "<directory-node-id>",
"limit": 256,
"authorization": {
"graphKeyId": "<device-id>",
"nonce": "<fresh-random-nonce>",
"signedAt": "<current-ISO-timestamp>",
"signature": "<base64-DER-signature>"
}
}Response shape:
{
"chain": [
"<signed-authority-record>"
],
"head": "<authority-head>",
"nextAfterSequence": "<cursor-or-null>",
"signingKeys": "<signing-key-map>"
}A device chain is a node's signed approval history. Binding proves persona membership; approval determines whether a device may act for a chained node. Existing chains remain enforced even when creation of new chains is disabled.
Read the directory
POST /v1/devices/log uses signed read device-log-read over {graphNodeId, afterSequence?, limit?}. Add authorization to send the request. graphNodeId is the directory being requested. The requester may read its own directory or a directory connected to its node by an active, unexpired edge in either direction.
afterSequence is an optional integer from 0 through 4294967295; limit is 1–256, default 256. The response excerpt and table list the core authority fields:
| Field | Contents |
|---|---|
chain | Signed authority records for this page |
head | Current sequence, record hash, epoch, root and approved/revoked state |
nextAfterSequence | Pagination cursor |
signingKeys | Public signing JWKs and lifecycle/recovery metadata |
Fetching or parsing this response does not verify its chain. Use the SDK device verification helpers with persisted trusted pins, and continue pagination until the verified state reaches the advertised head.
Append an authority record
POST /v1/devices/log/append takes {action, signature}. The device-log-append action contains graphKeyId, record, recordSignature, nonce and signedAt.
These records are required for clients to bootstrap a root when the server requires one, or approve a new device on an existing chain. Use buildDeviceRecord and the SDK signer’s signFeedRecord helper. The helper name and signing domain are compatibility identifiers for this core device-authority operation.
The inner record has kind, graphNodeId, epoch, sequence, previousRecordHash, issuerGraphKeyId, subjectGraphKeyId and issuedAt. Sign canonical JSON with v: "omnibus-feed-authority-v1"; then sign the outer action in the normal action domain. All signatures on these routes are canonical base64, low-S P-256 DER. Success returns {recordHash, head}.
| Kind | Authority and effect |
|---|---|
root | Genesis key opens epoch 1 |
approve | Approved usable device admits a sibling |
revoke | Approved device revokes a subject; a usable device may revoke itself |
reset | Eligible recovered, unapproved key closes the old epoch and opens another |
Each sequence is consecutive and links the preceding hash. Reset additionally includes closesRootRecordHash and resetReason, one of all-devices-lost, user-choice, or bootstrap. Eligibility requires a durable recovery marker for the current root and no chain revocation. A reset revokes displaced devices.
Limits and errors
A node can have at most 64 approved devices. Daily rolling limits are 8 approvals, 16 revocations and 2 resets per node. Responses use Cache-Control: no-store.
Device-authority codes include DEVICE_LOG_CONFLICT (409; refresh the head), DEVICE_LOG_NOT_APPROVED (403), DEVICE_LIMIT (409) and DEVICE_CHAINS_DISABLED (409). Also handle authentication failures, nonce replay, rate limits and unavailable responses by their HTTP status; this is not an exhaustive error-code list.