Approve a request

Once you created your request, you need to approve the challenge as the request creator before other users are notified to approve. To approve a request, you'll need to follow these steps:

Get the challenge

Given a request_id, first need to fetch the HSM challenge:

Bash

curl --request GET \
  --url https://api.vault.ledger.com/requests/{{request_id}}/challenge \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --header 'x-ledger-workspace: minivault'

JSON

{
"challenge": "eyJhbnRpcmVwbGF5IjoiM0JCMzdERkIxREYxRkQ5REUzNEZDQUZCQkVGNjZDQjVDMUVEMTU3MzEzNTRGQjAxNDZEQ0MyMjk3NjdEMzVCMSIsImRhdGEiOnsidHJhbnNhY3Rpb25fZGF0YSI6eyJhY2NvdW50X25hbWUiOiJDbGllbnRBIENPTCBUQlRDIDEiLCJhbW91bnQiOiIxMDAiLCJjdXJyZW5jeSI6ImJpdGNvaW4gdGVzdG5ldCIsIm1heF9mZWVzIjoiMjExIiwicmVjaXBpZW50IjoidGIxcTl3ZXh3OXB6amtsajd5cWxkNmczbGVqeHpyMHdndndoengwbmVrIn0sInRyYW5zYWN0aW9uX3R5cGUiOiJCSVRDT0lOX0xJS0VfU0VORCJ9LCJ0eXBlIjoiQVBQUk9WRV9UUkFOU0FDVElPTiJ9",
"id": 29
}

Decode the challenge

Decode the challenge to validate that the instructions HSM received is the same as the one you passed in your request:

Python

import jwt

// decode the challenge
challenge_data_bytes = jwt.utils.base64url_decode(challenge)

Javascript

import * as crypto from 'crypto';
import * as jwt from 'jsonwebtoken';

// decode the challenge
const decodedString = atob(dataToSign);
const jsonObject = JSON.parse(decodedString);

Example

{
  "antireplay": "3BB37DFB1DF1FD9DE34FCAFBBEF66CB5C1ED15731354FB0146DCC229767D35B1",
  "data": {
      "transaction_data": {
          "account_name": "ClientA COL TBTC 1",
          "amount": "200000000",
          "currency": "bitcoin testnet",
          "max_fees": "211",
          "recipient": "tb1q9wexw9pzjklj7yqld6g3lejxzr0wgvwhzx0nek"
      },
      "transaction_type": "BITCOIN_LIKE_SEND"
  },
  "type": "APPROVE_TRANSACTION"
}

Review the instructions closely to ensure they align with your initial intention before signing. This challenge involves trusted data signed by your API user, allowing the HSM to sign the actual transaction. For instance, if the recipient address differs from your request, it might indicate a potential man-in-the-middle attack. Regardless of the request, the true signed transaction will be sent to the recipient specified in this challenge. Don't trust, verify.

Sign the challenge

Sign the challenge with your user private key.

Python

import jwt

def sign_challenge(challenge: bytes, private_key_hex: str) -> str:
    private_key_bytes = bytes.fromhex(private_key_hex)
    challenge_data_bytes = jwt.utils.base64url_decode(challenge)
    jws = jwt.PyJWS()
    jws: str = jws.encode(challenge_data_bytes, private_key_bytes, algorithm="ES256")
    return jws

Javascript

import * as crypto from 'crypto';
import * as jwt from 'jsonwebtoken';

// // Data to be signed
const challenge = "eyJhbnRpcmVwbGF5IjoiM0JCMzdERkIxREYxRkQ5REUzNEZDQUZCQkVGNjZDQjVDMUVEMTU3MzEzNTRGQjAxNDZEQ0MyMjk3NjdEMzVCMSIsImRhdGEiOnsidHJhbnNhY3Rpb25fZGF0YSI6eyJhY2NvdW50X25hbWUiOiJDbGllbnRBIENPTCBUQlRDIDEiLCJhbW91bnQiOiIxMDAiLCJjdXJyZW5jeSI6ImJpdGNvaW4gdGVzdG5ldCIsIm1heF9mZWVzIjoiMjExIiwicmVjaXBpZW50IjoidGIxcTl3ZXh3OXB6amtsajd5cWxkNmczbGVqeHpyMHdndndoengwbmVrIn0sInRyYW5zYWN0aW9uX3R5cGUiOiJCSVRDT0lOX0xJS0VfU0VORCJ9LCJ0eXBlIjoiQVBQUk9WRV9UUkFOU0FDVElPTiJ9"

// Json to be sign
const decodedString = atob(challenge);
const jsonObject = JSON.parse(decodedString);
console.log("----- Json to be signed ----")
console.log(jsonObject);
console.log("----------------------------")

// Load the private key
const private_key_bytes = `-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEILMAPH5tb765vxNGiAmAaeBvFZnRtzTqfG/ZWQHXxv1NoAoGCCqGSM49\nAwEHoUQDQgAE5iRVj/FjRl3RLNmY0E8os9nyo/lxsII/WiAgNMq8z7tGFZ+G55g4\nqQwYCbfDE9in554X5KVTJqn2EDFl95QNPA==\n-----END EC PRIVATE KEY-----`
const privateKey = crypto.createPrivateKey({
  key: private_key_bytes,
  format: 'pem'
});
const privateKeyPem = privateKey.export({ format: 'pem', type: 'sec1' });
console.log('\nLoaded Private Key (PEM/SEC1):\n', privateKeyPem);

// Sign the data using the private key
const decodedData = Buffer.from(challenge, 'base64').toString('hex');
const jws = jwt.sign(Buffer.from(decodedData, 'hex'), privateKeyPem, {
  algorithm: 'ES256',
  header: {
    alg: 'ES256',
    typ: 'JWT'
  }
});

console.log("----- JWS Token ----")
console.log(jws);
console.log("--------------------")

Example

yJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbnRpcmVwbGF5IjoiM0JCMzdERkIxREYxRkQ5REUzNEZDQUZCQkVGNjZDQjVDMUVEMTU3MzEzNTRGQjAxNDZEQ0MyMjk3NjdEMzVCMSIsImRhdGEiOnsidHJhbnNhY3Rpb25fZGF0YSI6eyJhY2NvdW50X25hbWUiOiJDbGllbnRBIENPTCBUQlRDIDEiLCJhbW91bnQiOiIxMDAiLCJjdXJyZW5jeSI6ImJpdGNvaW4gdGVzdG5ldCIsIm1heF9mZWVzIjoiMjExIiwicmVjaXBpZW50IjoidGIxcTl3ZXh3OXB6amtsajd5cWxkNmczbGVqeHpyMHdndndoengwbmVrIn0sInRyYW5zYWN0aW9uX3R5cGUiOiJCSVRDT0lOX0xJS0VfU0VORCJ9LCJ0eXBlIjoiQVBQUk9WRV9UUkFOU0FDVElPTiJ9.F4NFOkcoQaAdxRwLQ_-QUal-XbBNhg-yjiTW_ycLmqA-wLrmpRpJ0owxjcf_QAkLyxWlkGpxH9gaymvsAl2KDA

With privatekeybytes the PEM format bytes of the private key.

-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIDN4pKvYZtwGLC/XiUKdUjPJJGTRd1MQxVKsiaWEAY1OoAoGCCqGSM49
AwEHoUQDQgAEdcIngZ7X7X5sipnIuP3rt1w6mg3V9LQE4txm5cx0tvaDxon+W6Kx
CBtTMvPCR5D9a9Nab2cNEjvKePWyzOHqMg==
-----END EC PRIVATE KEY-----

JSON Web Signature details

And jws the signed challenge / jws object. The resulting jws consists of three parts: the JWS Header, the JWS Payload, and the JWS Signature. The three parts are base64url-encoded and concatenated in that order being separated by period ('.') characters.

Approve the request

Once you signed the challenge use it to post your approval on the approve request endpoint:

Bash

curl --request POST \
  --url https://api.vault.ledger.com/requests/{{request_id}}/approve \
  --header 'authorization: Bearer {{access_token}}' \
  --header 'content-type: application/json' \
  --header 'x-ledger-workspace: <workspace name>' \
  --data '{
      "jws": "{{jws}}"
  }'

JSON

{
"created_by": {
  "id": 24
},
"created_on": "2024-01-24T08:07:08.007892+00:00",
"expired_at": "2024-01-31T08:07:08.007837+00:00",
"id": 29,
"status": "PENDING_APPROVAL",
"target_id": 305,
"target_type": "BITCOIN_LIKE_TRANSACTION",
"type": "CREATE_TRANSACTION"
}

If the response status is 200, the response payload will be the request with its new status, in our case we are still waiting for another approval from a second user so the status stays in PENDING_APPROVAL.