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.
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 buildsmessage 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.
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.
ed25519 challenge as the endpoint returns it (ids, keys and timestamps are a run’s own; message carries the nine lines joined with \n):
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.
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.

