Explore & Design
Explore & DesignDevelop & IntegrateEmbedded Wallet GuidesChangelogCommunityStatusRequest Demo

API Co-signers Architecture Overview

Suggest Edits

How automated MPC signing works

Overview

Similar to how the MPC-CMP algorithm is used to sign transactions and approve workspace configuration requests via a mobile device, the API Co-signer participates in a multi-signer MPC process. This process involves a set of independent Co-signers operated by Fireblocks, known as Cloud Co-signers, each of which holds a private key share. Refer to this MPC-CMP article to learn more about the API Co-signer's role in implementing the Fireblocks MPC signing algorithm.

The Co-signer eliminates the need for manual user input through the Fireblocks mobile application by automatically signing transactions and approving requests. By hosting the Co-signer in your environment and connecting it to your workspace using API users, you can configure the Transaction Authorization Policy (TAP) to designate the API user that is paired with the Co-signer to automatically sign transactions that meet the criteria defined in the policy.

To automate transaction signing, host the API Co-signer in your environment on a machine or virtual machine (VM) that supports enclaves. Fireblocks API Co-signers operate on Intel SGX, AWS Nitro, or Google Cloud Confidential Spaces enclaves. They can be deployed on major cloud platforms such as Azure, AWS, Google Cloud, IBM Cloud, and Alibaba Cloud, as well as on-premises with Intel SGX-capable servers.

Fireblocks has fully integrated AWS Nitro Enclave technology. If you are currently using KMS-based AWS API Co-signers, it is recommended to upgrade to the latest Nitro version for enhanced security and performance.


Observe the diagram below, which illustrates the relationship between the customer's API Co-signer, mobile device, API users, and the Fireblocks Cloud Co-signers #1 and #2.



Refer to the articles below for detailed information on the specific architecture of each type of enclaved Co-signer:



Using API users to connect the Co-signer to your workspace

To connect a new or existing Co-signer to your workspace, pair it with an API user from the workspace. Existing Co-signers are typically associated with another workspace within your organization.

Pairing the Co-signer is performed using a JWT-encoded Pairing Token obtained from the Console for a specific API user. This token is used during Co-signer installation to pair the initial API key, enabling communication with Fireblocks' SaaS. The Co-signer is identified exclusively by the workspace and the API user used to establish the connection.

The pairing process for the first API user requires admin-level access to the Fireblocks Console and root access to the Co-signer’s VM. During this process, you will provide the Co-signer with a pairing token linked to the API user, enabling the platform to recognize the Co-signer and associate it with the Workspace.

You can pair multiple API users to a single Co-signer. Additionally, API users from different Workspaces can be paired with the same API Co-signer, except when using the GCP Confidential Space Co-signer.


Connecting your business logic to the Co-signer

You can optionally connect your business logic to the Co-signer through a feature called a Callback Handler, configured per API user. The Callback Handler is an HTTPS server that receives requests from the Co-signer at a designated endpoint whenever a transaction signing or configuration approval is triggered for an API user. The Callback Handler responds with an action, such as approving or denying the request. If no Callback Handler is configured, the Co-signer will automatically sign or approve all requests for that API user.

Within a single Co-signer, some API users can operate with a configured Callback Handler, while others can function without it. When configuring a Callback Handler for a paired API user, you specify the URL of the Callback Handler server and select a secure communication method to establish a secure channel.

Refer to Setup API Co-signer Callback Handler to learn more about it.



Installing an API Co-signer

Available API Co-signer types

Fireblocks provides multiple deployment options for API Co-signers, available in both cloud environments and on-premises, in regions that meet the necessary enclave technology requirements. These deployment options leverage various enclave technologies to safeguard your MPC key shares, allowing you to select the solution that aligns best with your production environment requirements.

For detailed step-by-step installation guides for each Co-signer type, refer to the articles below:


Available enclave types

Learn more about the enclave technologies Fireblocks uses by referring to the following resources:



Configuring your workspace to sign using an API Co-signer

To enable the API Co-signer to participate in MPC signing and configuration change approvals, it must be paired with an API user from your workspace. Once the pairing process is completed successfully, a unique set of MPC key shares and workspace configuration keys is generated for the API user. These keys are securely stored within your Co-signer and Cloud Co-signers #1 and #2. The key shares facilitate automatic signing for transactions initiated by you.

Note that it must be an API user with the role of Signer or Admin, so it will have MPC key shares and be able to sign.

To activate automatic signing through the Co-signer, configure the Transaction Authorization Policy (TAP) to designate the API user paired with the Co-signer as the signer. When a transaction you initiate meets the criteria defined in the policy, it will be automatically signed by the Co-signer associated with the configured API user.

The process of generating and signing a Fireblocks transaction using the Fireblocks REST API, the API Co-signer, and the optional Callback Handler proceeds as follows:

  1. A new transaction is initiated using the Fireblocks API and generated on the backend.
  2. The transaction is evaluated against your TAP to determine if it is authorized.
  3. 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.
  4. The API Co-signer, hosted in your secure environment, polls the Fireblocks SaaS for transactions requiring signing. If a transaction is available, the SaaS immediately provides the transaction details.
  5. If a Callback Handler is configured for the API user designated as the signer, the API Co-signer sends a secure approval request to the Callback Handler.
  6. If the Callback Handler responds with "approved," the transaction is signed in coordination with Fireblocks' Cloud Co-signers. If the response is "rejected," the transaction is declined. If the Callback Handler does not respond within 30 seconds or returns "retry," the request fails. Refer to Setup API Co-signer Callback Handler to learn more about it.


Manage the Co-signer's paired API users and Callback Handlers

Configuring the Co-signer from the Console and Fireblocks API

Once the Co-signer is connected to the workspace, it can be managed through the Co-signers Management tab located in the Developer Center of the Fireblocks Console.

You can also use the Co-signer APIs (beta) for that.

Common Co-signer operations:

  • Pair an additional API User - requires the workspace owner approval
  • Configure the Callback Handler of an API user - requires the workspace owner approval
  • Unpair an API User (formerly known as re-enroll API user) - requires admin approval
  • Rename the Co-signer
  • Retrieve information about the Co-signer

📘

The Pair an additional API User and Configure the Callback Handler of an API user are available from the Console and APIs only for users who installed the latest Co-signer versions.

Refer to API Co-signers versions for more details


Configuring the Co-signer from its host machine

The AWS Nitro Co-signer and all types of SGX Co-signers can also be configured locally from the host machine using CLI commands. Refer to the Operating the Co-signer article for more details.

Due to Google Cloud's Workload container architecture, the GCP Confidential Space Co-signer can only be managed through Fireblocks' SaaS. Configuration operations must be performed within the workspace to which the Co-signer is connected, using either the Console or APIs. Consequently, the GCP Confidential Space Co-signer is restricted to a single workspace.



Using the Communal Test Co-signer


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


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 installing and configuring your own.

The Communal Test Co-signer is hosted and managed by Fireblocks and serves 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.

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 are 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.

Updated about 4 hours ago