API users

API users share all the characteristics of a Vault user: they have a seed, a device ID, and a name. They have the same rights as regular Vault users.

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.

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:

# 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_.

# 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

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

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

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

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

The Vault then generates a UUID.

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

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.

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:

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.