Skip to main content
Some API calls (for example, v3/api/servicedesk/approve) require an additional signing process with the maker/authoriser private key, typically when the maker confirms/authoriser approves an instruction (see section “4. Confirm instruction as maker” below). Before submitting the instruction to the HSM, you will need to sign the request payload with api_user_pri_key (API user private key). The content that must be signed is the stringified value of a part of this payload. For more details about a stringified value, see json-stable-stringify
The signed payload must not include optional and empty fields
The content to sign is the stringified value of the object named request and the resulting signature string should substitute placeholder $$REPLACE. Assume the maker is confirming instructions, retreive the instructions using the API v3/api/servicedesk/pending, the response is like (no field ordering)
Here the request payload needs to be ordered like,
This is the string to be used for generating the signature using api_user_pri_key, use it as value for signature field in the request. Below is an example of how to sign it in Python:
You will obtain the payload below (prettified for the documentation) to be submitted to the API:
Note: Please make sure you submit the same ordered request payload in the request body as well.

Multiple pending instructions for a single service request

For most Service Desk products, one service request produces exactly one instruction to sign, and v3/api/servicedesk/pending returns the single object shown above. Some products can produce more than one instruction from a single service request — for example, ETH Validator Consolidation and Transition when a service request’s migrations array contains more than one entry: each entry needs its own signature. In that case, v3/api/servicedesk/pending returns a JSON array of {request, signature} objects instead of a single object:
Sign each entry, then submit all of them in a single call to v3/api/servicedesk/approve by replacing request with the array of signed {request, signature} pairs, keeping the same requestId. The top-level signature field is not used in this case and can be omitted:
This is backward-compatible: every product that produces a single instruction is unaffected and continues to submit request as a single object with a top-level signature, as shown earlier in this section.