Skip to main content
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 ( for an EVM controller, for a Solana one) 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

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, in the scheme verificationMethod names, and submits { challengeId, signature } as identityProof when creating or updating the machine. The orchestrator resolves identityRef through the MCR API first and answers 403 MACHINE_NOT_ACTIVATED unless the machine is indexed by the MCR, active, bonded and homed on peaq or Solana with a controller key. For a peaq-homed machine that key is the EVM address in peaqos.operator; for a Solana-homed machine it is the base58 peaqos.controller, or peaqos.owner when controller is null or absent (a malformed controller or the all-zero key 11111111111111111111111111111111 is refused and never falls back to the owner; peaqos.operator of a Solana-homed machine is never read). A machine activated moments ago fails until the MCR indexes it. Only that controller’s signature, in the scheme the challenge names, is accepted. An address DID (did:peaq:0x…) returns 400 VALIDATION_ERROR, and an unreachable MCR 503 PEAQOS_IDENTITY_UNAVAILABLE.
If a proof is submitted past expiresAt the orchestrator returns MACHINE_IDENTITY_PROOF_EXPIRED for an eip191 proof and 401 PROOF_EXPIRED for an ed25519 one; the caller must re-challenge.

Signing a challenge

The server builds message and seals the signer, the scheme and the expiry into challengeId. The client signs the returned message exactly as it is, line breaks included, and sends { challengeId, signature } back as identityProof. The scheme follows from the key the MCR resolved for the machine, never from a client flag: An ed25519 identity challenge message has nine lines; the eip191 message keeps its existing form.
A worked example from the shared test vectors (orchestrator apps/api/test/fixtures/ed25519/challenge-vectors.json, entry machine-identity.valid): this message, signed by the key 2btPWhNDLVBF1f2ojBThHdBj8wU7hahxdx6jgsk5ZVZr, gives the signature 5t3FMU5Vmdv26EoMoRDss4AqHomwoAjT5FQRhjZq4HHkh9ReWMeCHNs6umGx7V85mwDDh1DSSeM422RKmjavGzUY. Verifying that signature over the message’s UTF-8 bytes under that key succeeds; change any line and it fails.
An ed25519 challenge as the endpoint returns it (ids, keys and timestamps are a run’s own; message carries the nine lines joined with \n):
A challenge is stateless: the scheme, the signer and the expiry are HMAC-sealed into challengeId, no nonce is consumed, and a { challengeId, signature } pair is accepted again until expiresAt (10 minutes by default, PEAQOS_IDENTITY_CHALLENGE_TTL_MS and PEAQOS_AGENT_PAIRING_CHALLENGE_TTL_MS; a session token lasts 1 hour, PEAQOS_AGENT_PAIRING_SESSION_TTL_MS). For an ed25519 challenge the orchestrator answers these codes; an eip191 proof keeps the MACHINE_IDENTITY_PROOF_* codes. The full contract (common rules, both message layouts, the shared vectors) is the SVM-SIGN Wire Contract.

Machines

GET /machines

Returns machines that carry a stored identityProof for their identityRef. The list does not re-check , so it can include a machine that no longer resolves; GET /machines/:machineId re-verifies. Draft machines without a stored proof are filtered out.

POST /machines

Creates a machine record. Requires identityProof when identity verification is enabled.
Errors: MACHINE_IDENTITY_PROOF_REQUIRED, MACHINE_IDENTITY_PROOF_INVALID, MACHINE_IDENTITY_PROOF_EXPIRED (eip191 proofs); PROOF_METHOD_MISMATCH, PROOF_SIGNATURE_INVALID, PROOF_SIGNER_MISMATCH, PROOF_EXPIRED (ed25519 proofs, see Signing a challenge); MACHINE_IDENTITY_EXISTS, MACHINE_NOT_ACTIVATED, 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.

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 an eip191 proof that does not recover to an MCR controller returns MACHINE_IDENTITY_PROOF_INVALID; an ed25519 proof that does not verify returns PROOF_SIGNATURE_INVALID, and one whose sealed controller is no longer the MCR controller returns PROOF_SIGNER_MISMATCH. MCR resolution failures return PEAQOS_IDENTITY_UNAVAILABLE. identityProof on this route is for a machine that was created without one: a machine created with a proof activates with { "status": "active" } alone, and the orchestrator re-checks the stored proof against a fresh MCR resolution.