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:

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

Decoding 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

Example

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

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

Example

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

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.