# Device authority

Read and append device approval history.


**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.

```http
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:

```json role="response"
{
  "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.


**Does not establish**
A quarantined key may read its own directory, device list and handle, renew under lifecycle rules, and revoke itself. It cannot perform ordinary graph operations. Successful AuthenSee recovery alone does not approve it, and a signed directory must still be verified locally.