Overview

Fireblocks’ API users allow you to automate your organization’s financial operations to help ensure smooth uninterrupted business.

You can set up API users to do the following:

• View the status of your workspace
• Initiate workspace operations
• Automatically approve workspace operations
• Automatically sign transactions
• Integrate your Fireblocks account with third-party applications

API user creation process

Depending on an API user’s workspace role and what you want it to do, the steps involved in creating it vary.

For read-only or for initiating workspace operations

1. In the Fireblocks Console, go to Settings  > Users and verify whether you can add users. If you can't, contact Fireblocks Support.
2. Generate a CSR file as described below.
3. Create the API user in the Console.
4. Get Owner and Admin Quorum approval to add the API user to the workspace.
5. Pair the API user with your client code.

For approving workspace operations or signing transactions

1. In the Fireblocks Console, go to Settings  > Users and verify whether you can add users. If you can't, contact Fireblocks Support.
2. Configure a server for the API Co-Signer that will host the API user. Note that for testnet workspaces, you can choose between configuring an API Co-Signer or using the Fireblocks Communal Co-Signer.
3. Generate a CSR file as described below.
4. Create the API user in the Console.
5. Get Owner and Admin Quorum approval to add the API user to the workspace.
6. Get the Owner to approve the API user share.
7. Pair the API user with your API Co-Signer.

Generating a CSR file

A Certificate Signing Request (CSR) file is required to authenticate an API user. The API user and the CSR file together validate that the logged-in API user is actually the API user defined in your workspace.

We do not recommend using the same CSR file for multiple API users in your Mainnet workspace. However, you can use the same CSR file for multiple API users in your testnet workspace to verify their functionality, or when all the API users using the same CSR file have read-only permissions.

To generate a CSR file for your API user, run the following command to generate an RSA 4096 private key (stored in fireblocks_secret.key). The only CSR attribute you are required to provide is your organization name. The rest of the attributes can be empty. 

openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr -subj '/O=<your_organization>'

Creating an API user

API users in your workspace must first be created in the Console. Note that only the workspace Owner, Admins, and Non-Signing Admins can create API users.

To create an API user:

1. In the Fireblocks Console, go to Developer center > API users.
2. Select Add API user.
3. On the Add User dialog, complete the following fields:
   1. • Name: Enter the name you want to give the API user in your workspace. You can enter up to 30 characters.
      • Role: Select the user role you want to assign the API user.
      • CSR File: Attach the CSR file you generated for this API user.
      • If you create the API user to pair it with a Co-signer, so you can automatically sign transactions and approve workspace configuration requests:
        • Co-Signer Setup:
          • Select the Proprietary SGX machine option if you plan to install a new Co-Signer or connect an existing Co-Signer to the workspace. Select this option even if you plan to install a different Co-signer type.
          • If you are in your testnet workspace, you can select the Fireblocks Communal Test Co-Signer option to automatically connect the API user to the Fireblocks Communal Test Co-signer.  Learn more about the different workspace types.
        • First user on this machine (this only applies to SGX Co-signers): If you plan to use the API user to install a new SGX Co-signer, select this checkbox. Otherwise, leave it empty.

          Note

          While the Co-signer does not use the CSR file to connect to the workspace, you must still provide it. This is necessary because the API user can be used to make API calls.

4. Select Add User.

This submits a request to the workspace Owner and Admin Quorum to add the API user to the workspace. After they approve it, you can continue the onboarding process.

Note that when you create an API user that can sign transactions, the workspace Owner must approve its MPC key share.

Whitelisting IP addresses for an API user

You can whitelist specific IP addresses for each API user. This restricts the API user from being used on unknown networks and only allows it to be used with the addresses you trust. Limiting those addresses mitigates the scenario where an attacker steals your API user and uses it from any machine on the internet.

Fireblocks highly recommends whitelisting IP addresses for all of your API users.

Retrieving an API user’s pairing token

To retrieve your API user’s pairing token:

1. In the Fireblocks Console, go to Settings > Users.
2. Select Pending setup on the API user’s row to copy its pairing token from the context menu.
3. Use the pairing token to add the API user to your API Co-Signer.

Pairing additional API users with the API Co-Signer

The Fireblocks API Co-Signer supports signing and approving with multiple API users. These users can be from either the same workspace or different workspaces. To view all users currently paired with an API Co-Signer, their user IDs, and their associated callback handler URL if available, run the following command:

./cosigner list-users

To add an additional API user to an API Co-Signer, run the following command:

./cosigner add-user

Next, enter the following inputs:

• Pairing Token: Enter the pairing token you retrieved.
• Callback Handler URL: Enter the callback handler’s URL address. Leave this blank if you aren’t using a callback handler.

To use a Callback Handler, select one of the following authentication methods.

• Public Key (recommended): Enter the public key of the Callback Handler.
• Certificate: Fetch the certificate from the Callback Handler URL. You can also copy the certificate and paste it here if you have it available.

After the authentication process, make sure you see “User added successfully.” The output should look something like this:

root@VM-SGX-US-2:~# ./cosigner add-user
Please enter pairing token from the fireblocks console
ey…UA4
Please enter callback URL (if using callback URL, else empty)
https://…
Please select one of the callback authentication options: (1)-PUBLIC KEY, (2)-certificate
1
Please paste your callback public key
-----BEGIN PUBLIC KEY-----
MI…QAB
-----END PUBLIC KEY-----

User added successfully
Uploading logs to Fireblocks
Physical Device ID: a…a

Retrieving an API user

When you want to use an API user for a specific operation, you’ll need to retrieve it:

1. In the Fireblocks Console, go to Settings > Users.
2. On the API user’s row, select Copy API User next to its name. If you do not see the key icon next to the API user’s name, refresh your browser tab.
   

Learn more about the Fireblocks API in the developer portal.

Need help?

Submit a request to Fireblocks Support.