Explore & Design
Explore & DesignDevelop & IntegrateEmbedded Wallet GuidesChangelogCommunityStatusRequest Demo

Installing an API Co-signer

Suggest Edits

In addition to manual transaction signing and workspace configuration change approvals using mobile devices, Fireblocks provides automated signing and approval through an API Co-signer that customers can install in their environment. This solution is ideal for workspaces managing high transaction volumes, frequent activity, fast signing times and 24/7 customer access.


Overview

The API Co-signer is a customer-owned component installed and hosted within their environment. Like the MPC-CMP algorithm used for signing transactions via a mobile device, the API Co-signer participates in a multi-signer MPC process alongside a set of independent Co-signers operated by Fireblocks, known as Cloud Co-signers, each holding a private key share.

The API Co-signer holds two types of keys:

  • MPC key shares: Used to sign transactions that are associated with your Fireblocks Vaults and derived from the Owner's set of key shares.
  • Workspace configuration change keys: Used to approve configuration changes in your workspace, such as creating new wallets.

The API Co-signer connects to a workspace by pairing with at least one API user. Based on the API user's role, it gets linked to an MPC key share and/or a workspace configuration change key during pairing. A single API Co-signer can store and manage multiple API users and their associated signing and approval keys, even across different workspaces.

Note that approving workspace configuration changes requires an API user with the Admin or Non-Signing Admin role.

Additionally, you can configure each API user in the API Co-signer to interact with a customer-owned business logic server using the Callback Handler functionality. The Callback Handler connects the API Co-signer to a predefined HTTPS server, which receives signing and approval requests for a specific API user, including the transaction data before signing or approval. The server then returns a response indicating the action to take.

The Callback Handler feature is optional. By default, the API Co-signer is configured not to use it and instead to sign the transaction or approval request.


Transaction flow via an API Co-signer

Below is a description of the process for generating and signing a Fireblocks transaction using the Fireblocks REST API, the API Co-signer, and the optional Callback Handler:

  • A new transaction is initiated using the Fireblocks API and then generated on Fireblocks' backend.
  • The transaction is evaluated against the workspace's Transaction Authorization Policy (TAP) and proceeds to the next step if it is authorized.
  • If an API user paired with the API Co-signer is configured in the TAP as a designated signer, the transaction will be sent to the API Co-signer associated with that API user. Note that it must be an API user with the role of Signeror Admin, so it will have MPC key shares and be able to sign.
  • The API Co-signer polls our SaaS for transactions to sign. If a transaction is available, we immediately respond with the details, and the transaction goes to the Co-signer for processing.
  • If the Callback Handler is configured for that API user, the API Co-signer sends a secure approval request to the customer's callback handler server.
  • Depending on the callback handler's response:
    • Once the Callback Handler responds, the transaction proceeds as follows: if the response is “approved,” the transaction is signed along with Fireblocks' Cloud Co-signers; if the response is “rejected,” the transaction is declined.
    • The transaction will fail if the callback handler does not respond within 30 seconds.

Available API Co-signer types

Fireblocks offers various API Co-signer deployment options, both in cloud environments and on-premises, utilizing Intel SGX and AWS Nitro Enclave technologies to protect your key shares.

Enclave technologies

You can learn more about these enclave technologies by referring to the following resources:


Installation guides

For a detailed step-by-step installation guides, refer to the articles below:


Fireblocks Communal Test Co-signer

Setting up a new Co-signer from scratch can be time-consuming. To accelerate development and prepare your workspace for automation and API-driven workflows, Fireblocks offers the option to use a Communal Test Co-signer before configuring your own.

The Communal Test Co-signer is hosted and managed by Fireblocks, serving all customers with Testnet workspaces. Any workspace owner can approve pairing API users with it, generate MPC key share sets, and use it to sign transactions. Please refer to this guide to learn how to use the Communal Test Co-signer.

Because Fireblocks can not take custodial responsibility for Mainnet workspaces due to legal regulations, this option is available only to Testnet workspaces.

When you start testing and verifying your signing or approval automation workflows, we recommend setting up your self-hosted API Co-signer instance and replacing the Communal Test Co-signer as soon as your instance is ready. To stop using the Communal Test Co-signer, unpair or delete the API users that were paired with it.

Once an API user is created in a Sandbox workspace, it is automatically paired to the Fireblocks Communal Test Co-signer, which holds the MPC key shares of all the API users in the Sandbox environment across all the workspaces.


API Co-signer Security Checklist

  • Use a clean, hardened machine for the Callback Handler server, with access restricted to authorized personnel only. For more details, refer to the API Co-Signer Recommended Defense and Monitoring Systems article.
  • Configure your network rules, cloud resources, and required policies according to the instructions provided in each API Co-signer installation guide.
  • Use the Callback Handler to log all approval requests, and consider utilizing it to implement additional programmatic protection logic against malicious withdrawals.
  • Create TAP rules that prevent API users from initiating transfers above a specific amount threshold within a certain timeframe, and require additional manual approval. These rules should apply globally to all withdrawals and withdrawals from specific external user wallets.
  • Fireblocks advises against disabling Linux UEFI secure boot on your API Co-signer virtual machine, as this goes beyond the security risks introduced by not validating kernel code. We recommend working around any issues you have instead. Using TrendMicro Deep Security agent on Ubuntu 20.04 is one option for secure boot support.

Updated 6 days ago