API Co-Signer Callback

Overview

The Fireblocks API Co-Signer allows you to automate approvals and signing for transactions and workspace changes. This is ideal for any workspace expecting a high volume of transactions, frequent workspace activity, or requiring 24-hour access.

The API Co-Signer is a component that holds an MPC key share of your Fireblocks Vault and a Configuration Change Key:

  • MPC key share: Used to sign transactions initiated via the API.
  • Configuration Change Key: Used to approve new wallets in your workspace. Configuration changes require an API user with the Admin user role.

Additionally, you can configure the API Co-Signer with a Co-Signer Callback Handler. The Callback Handler is a predefined HTTPS server that receives requests from the API Co-Signer and returns an action. The Callback Handler typically integrates user-facing apps with a Fireblocks workspace or includes market signals in the transaction approval process.

Want to know more?

Visit our Help Center to learn more about installing and maintaining the API Co-Signer.

Callback Authentication

When your API Co-Signer is configured with a callback, it sends a POST request to the callback handler. The POST request contains a JSON Web Token (JWT) encoded message signed with the API Co-Signer's private key. The Callback Handler uses the API Co-Signer's public key to verify that every incoming JWT is signed correctly by the API Co-Signer.

The Callback Handler's response is a JWT-encoded message signed with the Callback Handler's private key. This private key must be paired with the public key provided to the API Co-Signer during the Callback Handler's setup.

Callback Response Object

📘

New Callback Handler parameters

Beginning with API Co-Signer image 3.5.0, we made the following enhancements:

  • The Callback Handler can now return the new RETRY action. Learn more below.
  • When using API Co-Signers in a high availability configuration, the Callback Handler payload includes the signerId that will have the API user id value of the API user handling the request. The Callback Handler can use this parameter to identify which of the high availability servers made the request.
  • Known limitation: Currently the RETRY action supports only signing requests and not approval requests. In the next version it is expected to support both.

Learn more about updating your API Co-Signer here.

Below is the response expected from the Callback Handler for any request. If it does not respond within 30 seconds, Fireblocks fails the request.

ParameterTypeDescription
actionstringAPPROVE: Approves the request. For some configuration requests, a quorum may be required to approve the request.

REJECT: Denies the request. Even if a quorum of approvals is expected, one rejection denies the request.

RETRY: Retry the request until it times out, reaches the maximum number of retries, or the Callback Handler returns APPROVE or REJECT. Note that the timeout setting is fixed to 20 retries every 3 minutes, for a total of 60 minutes. There are future plans to introduce the option to configure the timeout at the tenant level. Additionally, retries are performed using identical parameters, so to prevent duplication, make sure your Callback Handler is properly configured to deal with the asynchronous nature of the calls.

IGNORE: This action is only supported for transaction and configuration approvals, not transaction signing. Dismisses the request without denying it, allowing the following approval requests to be processed. If a quorum is required to approve a request, the other approvers may approve this request independently.
requestIdstringThe unique identifier of the call, as received in the approval request.
rejectionReasonstring(Optional) Free text of the reason for rejection. This is used for logging purposes and recorded in the workspace's audit logs.