API Co-Signer Callback


The Fireblocks API Co-Signer allows you to automate approvals and signing for transactions and workspace changes. This is ideal for any workspace that expects a high volume of transactions, frequent workspace activity, or that requires 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.

Keys Generation

  • Generate a private key using the following command:
    openssl genrsa -out callback_private.pem 2048



Fireblocks only supports RSA key 2048 bit for public key callback authentication.

  • Export the public key from the previously generated private key using the following command:
    openssl rsa -in callback_private.pem -outform PEM -pubout -out callback_public.pem
  • Write your callback logic, which should include checking that the message can be decoded using the API Co-Signer public key. The API Co-Signer public key can be obtained by running the command:
    ./cosigner print-public-key
    Save the cosigner public key in a file on your Callback Handler server - cosigner_public.pem
  • Set up an HTTPS server with a certificate signed by a trusted CA. Make sure the route has a "/v2" prefix. Your callback handler endpoints should respond to requests that include a “/v2” prefix: https://your_callback_base_url/v2/tx_sign_request or https://your_callback_base_url/v2/config_change_sign_request

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.

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.

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.