Overview

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

🚧

Important

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.