IMPORTANT NOTE:

This article will be deprecated by February 28th, 2025. For all API Co-signer documentation, visit this overview article, which also links to updated Co-signer content in the Developer Portal.

Overview

You can configure multiple API Co-Signers to work in an active-active state to ensure that transaction operations adhere to your business continuity. If an API Co-Signer fails or becomes impaired, the other API Co-Signer(s) continues signing transactions.

Important:

This feature is available for API Co-Signers version 1.1.5 or later. To check the API Co-Signer version, run the following command on the API Co-Signer machine:

head cosigner -n 3 | grep VER

Refer to the following articles if an update is necessary:

Configuring the API Co-Signers to work in parallel

Upon completing the API Co-Signers setup and configuration (and, optionally, the Callback Handler), you can configure them to work in parallel using the Transaction Authorization Policy (TAP).

Each API Co-Signer must have at least one unique API user with the Signer role. Add these API users to the TAP's Designated Signers/Groups field for the transaction types you want the API Co-Signers to sign. You can add the API users individually or as a user group. Each user listed as a designated signer for the rule must be an API user. You cannot use a combination of API users and Fireblocks Console users. Refer to the following article to learn more about creating and modifying your TAP.

Once your Owner and Admin Quorum approve your TAP update now having multiple API Co-Signers working in parallel, the process of generating and signing a Fireblocks transaction is as follows:

A Console or API user creates and submits a transaction.
Fireblocks checks the transaction against your workspace's TAP to match it to the appropriate rule. In this example, the rule contains API users in its Designated Signers/Groups field.
Fireblocks calls all the API Co-Signers linked to the API users listed in the rule's Designated Signers/Groups field to verify that they are available to sign a transaction.
Fireblocks selects the first API user that responds with an available API Co-Signer to sign a transaction.
Fireblocks sends the transaction to the selected API Co-Signer.
If a callback handler is configured for the API Co-Signer, it determines whether the transaction should be signed or rejected according to your defined callback logic. The API user automatically signs the transaction if a callback handler is not configured.

Configuring TAP rules for a group of API Co-Signers

Exchange or fiat accounts

You cannot add multiple API users or a user group to the Designated Signers/Groups field in rules in which the Source field contains an exchange or fiat account. Doing so causes transactions that match that rule to fail automatically. You must assign a single API user in TAP rules for exchange and fiat accounts.

TAP Configuration

Depending on how you want to customize the TAP (i.e. whether you create inclusionary or exclusionary rules), you can use different methods to ensure transactions match the correct rule. In the following examples, Group 1 members are the API Co-Signers.

Method 1: Including API Co-Signers only for supported sources

Rule	Initiator	Type	Source	Destination	Whitelisted/ OTA	Amount	Time Period	Asset	Action	Approved By	Designated Signers/Group
1	Any	Tx	Any VA	Any	Whitelisted + OTA	$0	Single Tx	Any	ALLOW	-	Group 1
2	Any	Tx	Any	Any	Whitelisted + OTA	$0	Single Tx	Any	Approved By	Tywin	-

The rules in the table above state:

Rule 1: This rule allows any single transaction from any vault account to any whitelisted destination or one-time address with an amount greater than $0 from any asset. However, all transactions that match this rule must be signed by one of the Group 1 members.
Rule 2: This rule allows any single transaction from any source to any whitelisted destination or one-time address with an amount greater than $0 from any asset. However, all transactions that match this rule must be approved by Tywin.

Therefore, according to the first match principle, the API Co-Signers only sign single transactions in which the source is a vault account.

Method 2: Excluding API Co-Signers from unsupported sources

Rule	Initiator	Type	Source	Destination	Whitelisted/OTA	Amount	Time Period	Asset	Action	Approved By	Designated Signers/Group
1	Any	Tx	Any Exchange, Any Fiat	Any	Whitelisted + OTA	$0	Single Tx	Any	Approved By	Tywin	-
2	Any	Tx	Any	Any	Whitelisted + OTA	$0	Single Tx	Any	Approved By	Tywin	Group 1

The rules in the table above state:

Rule 1: This rule allows any single transaction from any exchange or any fiat account to any whitelisted destination or one-time address with an amount greater than $0 from any asset. However, all transactions that match this rule must be approved by Tywin.
Rule 2: This rule allows any single transaction from any source to any whitelisted destination or one-time address with an amount greater than $0 from any asset. However, all transactions that match this rule must be approved by Tywin and then signed by one of the members from Group 1.

Therefore, according to the first match principle, the API Co-Signers only sign single transactions in which the source is not an exchange or a fiat account.

Multiple API Co-Signer deployment options

Depending on your needs, API Co-Signers can be installed in the cloud, or on on-premise servers.

An example using three API Co-Signers in an active-active-passive architecture for the API Co-Signer cluster:

The two active-active API Co-Signers are deployed in different availability zones in Azure. This deployment configuration prevents a single point of failure and avoids any downtime.
A third, on-premise API Co-Signer, is ready for restoration and operation as a failover. This redundancy helps avoid downtime while updating or running maintenance on a cloud-based API Co-Signer.