Rotate Feed device credential

Replace the credential hash in a protected device assignment in the granted workspace, returning a one-time credential. An unassigned id can receive an assignment; this does not create an observed device row.

Outcome

Before you start

Verify the authenticated identity, exact environment and pinned approved organization context before preparing an action.
Development stores content without encryption and uses scoped SHA-256 identifier hashes. Staging and production require envelope encryption and a provisioned application root; missing custody does not permit plaintext.
The published application permission is feed:write. Discover a granted Feed workspace and bind that exact resource. Supplied identifiers and query selectors do not grant access.
Authorize the documented mirror, security, external-fetch, reporting, privacy or archival effects before CLI --confirm or MCP confirm:true. A GET request can initialize a local mirror.

Discover the target

topolo whoami --json
topolo actions get app_topolo_feed.devices.credential.rotate --detail --json
topolo resources topolo-feed --json
topolo workspaces list topolo-feed --json

Select the exact granted workspace id as FEED_WORKSPACE_ID. Fixture ids authorize no live operation.
Read observed device identifiers where available. A new assignment is a separate security decision, not proof of physical device enrollment.

Request

POST /api/analytics/devices/{deviceId}/credential

Save action input as payload.json. Inspect the plan for the exact path, query and body. Set FEED_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console, then perform the verification below.

Input fields

Field	Required	Type	Constraints
`deviceId`	Required	string	Intended physical device identifier in the granted workspace. Discover an observed id where available; a previously unassigned id can receive an assignment without creating an observed device row.; {"minLength":1}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "deviceId": {
      "type": "string",
      "minLength": 1,
      "description": "Intended physical device identifier in the granted workspace. Discover an observed id where available; a previously unassigned id can receive an assignment without creating an observed device row."
    }
  },
  "required": [
    "deviceId"
  ],
  "additionalProperties": false
}

Effects

Resolves the workspace through platform grants and can insert its identity-only local mirror before the route permission check. GET is therefore a mutation for action planning; it does not create a canonical workspace or change its name.
Refuses an assignment already bound to another workspace. Otherwise writes a new credential hash and assignment metadata under the protected device key.
The old credential becomes invalid for enrollment verification. The plaintext HTTP credential is returned once and is not retrievable later. CLI/MCP protect sensitive response fields and may return an opaque local reference; never expose its underlying value.
Creates no device observation, analytics event, hardware enrollment or proof of playback.

Interpret the response

Use response path $.device.device_id for feed_device. An empty list does not discover a target.

Retain the protected response reference through the supported secret handling flow and install it on the intended device through its approved enrollment process. Verify a subsequent accepted device event and observed activity separately. The rotation response alone does not prove the device came online.

The success schema below was checked against captured handler responses. Polymorphic configuration and protected device assignment fields vary; exact envelope and SQL row fields are source-reviewed. Error examples retain their actual refusal shapes.

Success schema:

{
  "type": "object",
  "properties": {
    "device": {
      "type": "object",
      "properties": {
        "device_id": {
          "type": "string"
        },
        "workspace_id": {
          "type": "string"
        },
        "credential": {
          "type": "string"
        },
        "rotated_at": {
          "type": "string"
        }
      },
      "required": [
        "device_id",
        "workspace_id",
        "credential",
        "rotated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "device"
  ],
  "additionalProperties": false
}

Worked examples

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. SQL result shapes are also reviewed against migrations and handlers; empty captures do not exercise every populated export store. Live publication and read-back are separate environment evidence. Refused examples demonstrate boundaries and must not be executed as successful workflows.

Successful request

Input · payload.json:

{
  "deviceId": "display-1"
}

CLI:

topolo actions validate app_topolo_feed.devices.credential.rotate --data @payload.json --json
topolo actions plan app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_feed.devices.credential.rotate",
    "input": {
      "deviceId": "display-1"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 201:

{
  "device": {
    "device_id": "display-1",
    "workspace_id": "feed_workspace_alpha",
    "credential": "[redacted synthetic credential]",
    "rotated_at": "2026-10-04T04:12:42.909Z"
  }
}

HTTP 201. Retain the protected response reference through the supported secret handling flow and install it on the intended device through its approved enrollment process. Verify a subsequent accepted device event and observed activity separately. The rotation response alone does not prove the device came online.

Another supported request

Input · payload.json:

{
  "deviceId": "display-1"
}

CLI:

topolo actions validate app_topolo_feed.devices.credential.rotate --data @payload.json --json
topolo actions plan app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_feed.devices.credential.rotate",
    "input": {
      "deviceId": "display-1"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 201:

{
  "device": {
    "device_id": "display-1",
    "workspace_id": "feed_workspace_alpha",
    "credential": "[redacted synthetic credential]",
    "rotated_at": "2026-10-04T04:12:42.911Z"
  }
}

Refused request · HTTP 403

Input · payload.json:

{
  "deviceId": "display-1"
}

CLI:

topolo actions validate app_topolo_feed.devices.credential.rotate --data @payload.json --json
topolo actions plan app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 403:

{
  "error": "forbidden"
}

HTTP 403. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Another supported request

Input · payload.json:

{
  "deviceId": "display-1"
}

CLI:

topolo actions validate app_topolo_feed.devices.credential.rotate --data @payload.json --json
topolo actions plan app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_feed.devices.credential.rotate",
    "input": {
      "deviceId": "display-1"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>",
    "confirm": true
  }
}

Captured local response · HTTP 201:

{
  "device": {
    "device_id": "display-1",
    "workspace_id": "feed_workspace_alpha",
    "credential": "[redacted synthetic credential]",
    "rotated_at": "2026-10-04T04:12:42.913Z"
  }
}

Refused request · HTTP 404

Input · payload.json:

{
  "deviceId": "display-1"
}

CLI:

topolo actions validate app_topolo_feed.devices.credential.rotate --data @payload.json --json
topolo actions plan app_topolo_feed.devices.credential.rotate --resource-type workspace --resource-id "$FEED_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 404:

{
  "error": "device_not_found"
}

HTTP 404. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Verify the result

Retain the protected response reference through the supported secret handling flow and install it on the intended device through its approved enrollment process.
Verify a subsequent accepted device event and observed activity separately. The rotation response alone does not prove the device came online.

Errors and recovery

forbidden (HTTP 403): Verify the active organization, application permission and granted workspace; an id or query parameter does not grant access.
device_not_found (HTTP 404): Inspect the exact handler refusal and correct the target, window, URL or confirmation before preparing another authorized request.

Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.

Recovery boundary

The previous credential cannot be restored by a published action. If the new credential is lost, a separately authorized rotation creates another credential and invalidates the current one. Never repeatedly rotate ahead of device installation.

List observed Feed devices: Return at most 1,000 devices observed in the granted workspace, ordered by most recent observation. Protected device references are decoded, credentials are excluded, and the local mirror may be initialized.

Evidence

Actual Feed Worker response using synthetic Auth, workspace grants, in-memory D1/KV and simulated source/notification transport. No live provider, encryption audit, device enrollment or external delivery is established. Credentials are excluded or explicitly redacted. SQL result shapes are also reviewed against migrations and handlers; empty captures do not exercise every populated export store. Live publication and read-back are separate environment evidence. Capture digests and test scenarios are retained in the source fixture records.

Rotate Feed device credential

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Successful request

Another supported request

Refused request · HTTP 403

Another supported request

Refused request · HTTP 404

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence