API Co-signers Architecture Overview

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 Policies 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:

• Intel SGX Co-signer architecture running in Azure, IBM Cloud or Alibaba Cloud
• Nitro Co-signer architecture running in AWS
• Confidential Space Co-signer architecture running in Google Cloud

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.

Callback best practices

When a signing or authorization request reaches the API Co-Signer, a callback is invoked with the transaction details. We recommend closely monitoring this communication to ensure the callback responds quickly and reliably, as MPC signing will not begin until the callback approves the request.