Register LAM User

warning

Using Ledger Authentication Module to authenticate via API will be supported until Q3 2024, if you are starting a new setup, we recommend using the new API User methods

LAM operator share all the characteristics of a Vault operator: they have a seed, a device ID, and a name. They have the same rights as regular PSD operator.

The main difference is that instead of having their secrets stored and handled by a Ledger Blue device, they are stored on your servers and stay available for LAM to be used when performing secure operations.

warning

The purpose of using hardware devices is to prevent your secrets from being accessible. Using a hardware secure element guarantees the isolation of your seed and other credentials. LAM is storing these credentials by accessing a special location. A special effort must be made to secure this location. Making these credentials available for read in another context would destroy the usefulness of the Vault as a security solution.

Securing user credentials

The LAM can be operated in two different modes:

The user secrets and certificates are stored on a mounted docker volume, usually on the filesystem of the machine running LAM. Every possibility offered by Docker volumes can be used here.

Option 1. Using the File System

Cert Storage

A typical configuration for environment variables:

Copy

Copied

# Select the backend to use
CERT_STORAGE_BACKEND=FILESYSTEM
CERT_STORAGE_PATH=/path/to/cert

User storage

Configuration keys for the user storage are roughly equivalent but prefixed with USER_ instead of CERT_.

Copy

Copied

# Select the backend to use
USER_STORAGE_BACKEND=FILESYSTEM

# The path on which the user secrets are stored within the docker container
USER_STORAGE_PATH=/path/to/secrets

Permissions

For now, you’re restricted to the Operator role. If the defined governance rules allow it, Operators are able to create and approve transactions, and review the content of accounts. API users are given extra read rights on all Vault objects (accounts, transactions, groups, etc.) which allows you to generate reports and oversee the activity on your workspace using API calls.
This also means that API users cannot be used when onboarding on the Vault. This process relies entirely on the use of Ledger Blue devices. The same goes when editing your partition, accounts, users, groups, and whitelists.

Create a new API Operator

Step 1. Create the request on LAM

Create a Create user request on LAM.
Define a username. The username must not contain any space.
Enter the appropriate port number.
Run the curl command or user postman.

Copy

Copied

export API_USER_NAME=api_lam_user
export LAM_ADDRESS='http://localhost:5000'  # if you run the LAM locally
curl -d "{\"name\": \"$API_USER_NAME\"}" -H "content-type: application/json" $LAM_ADDRESS/api_users
{
  "DEVICE_ID": "c0e0916fbcdee40e",
  "name": "api_lam_user",
  "role": "OPERATOR",
  "type_": "SOFT_PSD",
  "workspace": "ledger1"
}

The response contains a DEVICE_ID string that will allow the Vault to associate the user you invite with this device. At this stage, LAM has created and stored the seed of this device in its user_storage folder.

Step 2. Invite new API Operator to your Vault workspace

Connect to your workspace.
Click Users , in the left panel.
Click Invite user in the top right. The Invite new user modal opens.
Select API , then click Next .

invite new user

Enter the user’s Username. This name must be identical to the one provided by the API.
Enter the User ID (DEVICE_ID) provided by the API.

The Vault then generates a UUID.

Do another POST request on LAM using this UUID to accept the invitation as shown below:

Copy

Copied

curl -X POST $LAM_ADDRESS/api_users/$API_USER_NAME/register/bfdf2979-6d26-4b79-896b-5b7e218c8d9f
    {
        "success": true
    }

Step 3. Administrators must approve the request

Once done, a Create user request is created in your Vault workspace and Administrators must approve it. The required number of approvals depends on the Admin rule defined for the workspace.

invitation new user

Results

Once the request is approved, the new Operator can start using the API.

You can check that everything is functional by running the following:

Copy

Copied

curl -X GET $LAM_ADDRESS/users -H "X-Ledger-API-User: $API_USER_NAME"
{
  "edges": [
            {
                "cursor": 0,
                "node": {
                    "created_by": 5,
                    "created_on": "2020-05-07T10:38:39.211106+00:00",
                    "id": 11,
                    "is_api": true,
                    "key_handle": "119cb610ec3ae9200f2ffb0102dd8ff7d2370f7f0ea38701a3a73f734ab5be4254a68153d333e8ac6e7e1f720a3e6a49dd97d24f3eeb829996ba024e6bcbc00c",
                    "last_request": 1,
                    "pub_key": "04F3EF7351309162BC1E89EF60705D5BF6565442C27BB668857B0D46A8401F4A03E75B6364DA7F7B95F35D2AE96818E3EFA58C27C52C0009ED6FE2A04B14AC221D",
                    "role": "OPERATOR",
                    "status": "ACTIVE",
                    "user_id": "D0A187E8A2082C9E",
                    "username": "test_user"
                }
            }
        ],
        "page_info": {
            "count": 1,
            "has_next_page": false
        }

Note that this API user can be suspended or revoked from the workspace at any time like any regular Vault user.