API Co-Signer Callback


The API Co-Signer automates approving and signing transactions, and approving workspace changes. The API Co-Signer replaces using a mobile device for manual approvals. This is ideal for any workspace that expects a high volume of transactions, frequent workspace activity, or 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 for automated signing and approvals. The key share is used to securely sign transactions initiated via the API. The Configuration Change Key is used to approve new wallets in your workspace. Configuration changes require an API user with an Admin user role.

You can provision 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 approval, rejection, or ignore action. The callback handler is typically for integrating user-facing apps with a Fireblocks workspace or including market signals in the transaction approval process.

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. The private key must be the key paired with the public key provided to the API Co-Signer during the Callback Handler's setup.

Callback Response Object

The response expected from the API co-signer callback handler for any request. If the callback handler does not respond within 30 seconds, Fireblocks fails the request.

actionstringAPPROVE - Approves the request. For some configuration requests, a quorum of approvals from multiple users or devices may be needed to fully approve the request.

REJECT - Denies the request. Even if a quorum of approvals is expected for approval, one rejection fully denies the request.

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