Create an account

In this guide, we'll walk you through the essential processes to perform authenticated requests on Ledger Enterprise APIs as an API Administrator.

Prerequisite

To perform the following steps, your API Administrator must:

be registered and part of the right admin rule.
be authenticated

Create an account with policy

To ensure complete security in your workspace and handle on-chain requests using our security module, follow these guidelines to create accounts and prevent errors:

Maximum 200 accounts per hour (including the validation of their requests)
Create the accounts in sequence: create account 1 > approve account 1 request > Create account 2...

Building your request payload:

To build a payload to create a new account with policy, we need to know:

the account type (e.g, TRC20_LIKE)
the account index (e.g, 0)
the account name (max 19 characters, no special characters, e.g, USDT 1)
the account currency (e.g, tron)
the name of the policy used (e.g, Multipolicy 1)
(if token) the parent id (e.g, 95)
(if token) the contract address (e.g, TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9)

See the create request reference for more information.

The resulting request payload is the following:

{
  "data": {
    "account_type": "TRC20_LIKE",
    "account_data": {
      "index": 0,
      "name": "JST",
      "currency": "tron",
      "policy_name": "Multipolicy 1",
      "parent_id": 95,
      "contract_address": "TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9"
    }
  },
  "type": "CREATE_ACCOUNT"
}

Approve a request

Once you created your request, you need to approve the challenge as the request creator before other administrators 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:

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'

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

Decoding the challenge

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

import jwt

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

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

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

{
  "antireplay": "0D1B06079EE2DDF9E5220EFC36F401B8A3BBE1F2124F9DC89615DC5BC4D0AFD1",
  "data": {
    "account_data": {
      "contract_address": "TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7",
      "currency": "tron",
      "index": "2",
      "name": "TRC20 Account 2",
      "policy_name": "Test"
    },
    "account_type": "TRC20_LIKE"
  },
  "type": "CREATE_ACCOUNT"
}

Carefully review that what you are about to sign is the right instructions matching your initial intention. This challenge is the trusted data signed by your administrator that will allow the HSM to sign the true account.

This is an important step, when decoding the challenge from the HSM this need to be the exact same information the account creator passed in transaction_data.

Signing the challenge

Sign the challenge with your user private key

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

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("--------------------")

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

with privatekeybytes the PEM format bytes of the 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:

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}}"
  }'

{
"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.

Once this is done, the next important step is approving the request so the account is created.

PreviousAPI Administrator NextAPI functionalities

Last updated 7 days ago