Creating a Mainnet API User from the Desktop App or Cold Vault
Introduction
There are three steps to creating an API user for a mainnet Custody Infrastructure production deployment. First, generate keys for the user. Next, create a user via the desktop app or Cold Vault (depending on the system mode). Finally, register the user.
Cold Vault API Use
API users created via the Cold Vault in Cold-Driven mode are able to do two things a user created on the desktop in MPC-Driven mode cannot:
- Can approve Cold Vault transactions
- Can perform Cashbox actions
The process of creating an API user assumes you have already installed and configured your production Custody Infrastructure deployment and are familiar with the SDK.
Key Generation
Key generation is performed from the command line of the SDK. Generate keys for the API user by running the code below.
Example Input:
from ApiClient import ApiClient
from cryptography.hazmat.primitives.asymmetric import ec
private_key, public_key, typing_key = ApiClient.generateKeysForRemoteUser(curve=ec.SECP256K1())
print(public_key) # This prints both the typing and public keys
print(private_key)Example Output:
Typing Key: 0D4D2Z3MW3ZTRBWYH8D9N7I0Y99O22OIKO9T4GL17QAXQ3MQQCG51
Public Key: 040E734553F1...B5D9F8
Private Key: 12F1ABCD...Three keys are displayed in the following order. Save them to a safe place:
- Typing key (called verifying_key_base36_with_checksum in the API client code)
- Public key (called decoded_verifying_key in the API client code)
- Private key (called decoded_sign_key in the API client code)
About the Keys
The Public Key and Private Key are used by the SDK to encrypt and authenticate API traffic. The Typing Key is a base36-encoded hash of the Public Key and is required for user creation in the UI.
Always prefix the Typing Key with 0 before using it in the UI.
API user creation for Custody Infrastructure systems in MPC-Driven mode can be performed from the MPC desktop app by an Admin.
Log in to the MPC desktop.
Navigate to the User Management area and click the + button to create a new user.
Complete the following fields of the New User Creation dialog:
- First Name, Last Name: This will identify the API user in notifications and activity audits.
- Email: Enter a username for the API user in the form of an email address, for example: [email protected]
- Role: Choose the role that the API user will use. The API user will be governed by the same policies as any other user in that role.
- User Group: Choose the user group that the API user will be part of. The API user will be governed by the same policies as any other user in that group.
- Public Key: Here, insert the typing key received from running the script above, prefixed by 0 (zero). This is the FIRST key output by the script you ran earlier.
Important:
If the Typing Key does not begin with 0, add it manually. The UI requires this format.

Click Create.
Before the change comes into effect, it must be approved by the relevant admins.
Click My Changes.
The request details appear for verification.
Click Send Request.
The API user is created as soon as the request is approved according to policy.
Custody Infrastructure API User Registration
API user registration is performed from the SDK by running the following:
from ApiClient import ApiClient
public_key = "Enter here the public key received from the generateKeysForRemoteUser function above"
from MpcDriven.EnumTypes import SignatureType
signature_type = SignatureType.SECP256K1
# Register the user and capture returned values
name, new_user = ApiClient.registerMpcUser(
public_key,
signature_type,
"ip address of the MCS",
is_production=True,
is_strict=True
)
# ✅ This line confirms the response's organization name
assert name == "organization name" # Must match value set by GK8 support
new_user.generateNewAccessToken()Make sure to insert the public key from the first step above before running the code. Once completed, you are ready to run API calls. If no errors are returned, the user has been successfully created.
Store user keys to alternative location (optional)
The usual flow is to allow the Custody Infrastructure system to save the new user public and private keys to a secure location on your device. However, should you wish to store these keys in a different location, such as save them to a USB drive, or write them on paper and store in a safe place, follow this 2 step process:
Step 1: Generate and securely store the user keys
When creating a new user account, the context for the account must be set to GK8Context().
This prevents the creation of the GK8Storage.json file, which by default stores the public and private keys created for the new account. Instead, the keys are saved in memory and are lost when the session ends.
It is essential that the keys are saved to another location, such as a file generated by the administrator and stored on a USB drive. Alternatively, for optimal security, write down the keys on paper and store this in a secure location.
Generate the keys for the new user.
In your python script add the following:
This saves the values of the private, public and typing key as variables in the system memory.
Export the private_key and public_key values to a secure location in a format that satisfies the security needs of the organization, i.e. a JSON file to a USB drive.
The typing_key is used in the Desktop app when adding the new user to the system. This should also be saved or written down and kept for this use. However, it doesn’t need to be saved with the other keys or used with the API calls.
Step 2: Register the API user with the existing keys
Run a second python script to register the existing user with the API. Depending on how the keys were saved, the code should either call the keys from the saved location, ie. on a USB drive, or the administrator might need to manually enter the public and private keys that were saved in the previous step.
Define the private_key and public_key:
Create a newcontext:
Define the signature type:
Define the User keys by storing the keys to the helpers function:
Ensure that helpers library is imported - from gk8_sdk.Helpers import helpers
Finally assign the user data.
OR this could be written:
For a uMPC system is_impenetrable_vault_deployed will be False.
The user is now registered and can now make any API function call in the normal way, for example:
API users can be created from the Cold Vault in both Cold- and MPC-Driven modes. This procedure must be completed by an admin using the Cold Vault itself.
Open the User Setup menu on the Cold Vault. Fill in the following:
- First Name
- Last Name
Choose MPC User and click ok.
In the Enter the public key box, input the Typing key, the first key listed from the keys generated earlier.
Click Continue.
At this point, move to the MCS and run the following code:
public_key = "Enter here the public key here" # Use the second key generated in the key generation step above.
name, new_user = ApiClient.registerColdRemoteUser(
public_key,
"MCS IP address here",
is_production=True,
is_strict=True
)
new_user.generateNewAccessToken()Verification
Verify the user was created successfully by making an API call. We recommend running getAllUsers() as you can check the output and see that your newly created API user exists. Any API call can be used to verify, as only a successfully created and authenticated user can run an API call.
Be sure to print the results so you can see that everything is functioning as expected:
users = new_user.getAllUsers()
print(users)