Machine Markets: Machines & identity

These endpoints register and update machine records in the orchestration service. When PEAQOS_MACHINE_IDENTITY_VERIFICATION=required is on (production default), the caller must include a signed controller proof obtained from a before the orchestrator will persist any machine-bound write. See the Machine Markets overview for base path, auth model, common envelopes, and error codes.

`Machine` type

type Machine = {
  id: string;
  displayName: string;
  status: "draft" | "active" | "degraded" | "blocked" | "archived";
  ownerId: string;
  identityRef: string;          // did:peaq:0x... or peaqos:machine:<id>
  identityProof?: {
    method: "eip191";
    identityRef: string;
    signerAddress: string;
    challengeId: string;
    verifiedAt: string;
    challengeExpiresAt: string;
    controllerAddresses: string[];
    resolutionSource: "peaqos-mcr";
  } | null;
  machineType: string;
  runtimeProfile: string;
  capabilities: string[];
  labels: Record<string, string>;
  policyIds: string[];
  skillKeys: string[];
  createdAt: string;
  updatedAt: string;
};

Machine identity

`POST /machine-identity/challenges`

Creates a short-lived challenge for a peaqOS machine identity. The caller signs message with the DID-controller private key and submits { challengeId, signature } as identityProof when creating or updating the machine.

type CreateMachineIdentityChallengeRequest = {
  identityRef: string; // did:peaq:0x... or peaqos:machine:<id>
};

type CreateMachineIdentityChallengeResponse = ItemResponse<{
  challengeId: string;
  identityRef: string;
  message: string;
  expiresAt: string;
  verificationMethod: "eip191";
  controllerAddresses: string[];
}>;

type MachineIdentityProofInput = {
  challengeId: string;
  signature: string;     // EIP-191 personal_sign
};

Challenges expire. If a proof is submitted past expiresAt the orchestrator returns MACHINE_IDENTITY_PROOF_EXPIRED and the caller must re-challenge.

Machines

`GET /machines`

Only returns machines whose identityRef resolves and whose stored identityProof matches controller data. Draft machines without a verified proof are filtered out.

type ListMachinesResponse = ListResponse<Machine>;

`POST /machines`

Creates a machine record. Requires identityProof when identity verification is enabled.

type CreateMachineRequest = {
  displayName: string;
  ownerId: string;
  machineType: string;
  runtimeProfile: string;
  identityRef: string;
  identityProof?: MachineIdentityProofInput;
  capabilities?: string[];
  labels?: Record<string, string>;
  policyIds?: string[];
  skillKeys?: string[];
};

type CreateMachineResponse = ItemResponse<Machine>;

Errors: MACHINE_IDENTITY_PROOF_REQUIRED, MACHINE_IDENTITY_PROOF_INVALID, MACHINE_IDENTITY_PROOF_EXPIRED, MACHINE_IDENTITY_EXISTS, PEAQOS_IDENTITY_UNAVAILABLE, VALIDATION_ERROR.

`GET /machines/:machineId`

The orchestrator re-verifies the persisted identity proof against peaqOS MCR data on every read. Returns MACHINE_NOT_ACTIVATED if the machine no longer resolves through MCR.

type GetMachineResponse = ItemResponse<Machine>;

`PATCH /machines/:machineId`

Partial update. identityRef is immutable once set; attempting to change it returns MACHINE_IDENTITY_IMMUTABLE. Identity proofs are re-verified on every update. Activating an unverified machine returns MACHINE_NOT_ACTIVATED. Submitting a proof that does not recover to an MCR controller returns MACHINE_IDENTITY_PROOF_INVALID. MCR resolution failures return PEAQOS_IDENTITY_UNAVAILABLE.

type UpdateMachineRequest = Partial<CreateMachineRequest> & {
  status?: Machine["status"];
};

type UpdateMachineResponse = ItemResponse<Machine>;

​Machine type

​Machine identity

​POST /machine-identity/challenges

​Machines

​GET /machines

​POST /machines

​GET /machines/:machineId

​PATCH /machines/:machineId

​Related