Skip to main content

​
Overview

The API Co-signer Callback Handler places your custom authorization logic at the signing boundary, separate from your application. When you configure a Callback Handler for an API user paired with a Co-signer, the Co-signer sends every signing or approval request for that user to your handler and requires its response before proceeding. This gives your organization an independent control point that continues to protect signing if your application or its API credentials are compromised.
The Callback Handler is a service hosted and managed by your organization. You build, host, and operate it in your own environment. The Co-signer acts as its client and waits for its response before proceeding with a signing or approval request.
Your Callback Handler can apply business, security, or compliance logic before transactions are automatically signed or approved. If no Callback Handler is configured for an API user, the Co-signer automatically signs or approves all requests it receives for that user.

​
Security enforced at signing or approval time

Checks implemented inside your application run before a transaction request reaches Fireblocks. Your application alone enforces those checks, so a caller with valid API credentials can submit transactions without passing through them. The Callback Handler moves your custom validation into an independent authorization layer that the Co-signer invokes at signing or approval time. Your handler determines what should be signed or approved, and the Co-signer enforces through Multi-Party Computation (MPC) that only an approved request produces a valid signature. A compromise of your application or its API credentials therefore cannot bypass the Callback Handler.
You define the validation logic, and the Co-signer enforces the decision. Authorization and signing remain in separate trust domains, so your application cannot produce a valid signature by itself.
The trust boundaries look like this: Your Callback Handler can approve a request, but it cannot create a signature. The Co-signer participates in MPC signing only after the handler approves the request. See the API Co-signers Architecture Overview for how key shares are generated and protected. The Callback Handler complements the Fireblocks Policy engine rather than replacing it:

​
Built-in protections

The integration also protects communication and failure behavior by default:
  • Authenticated communication: Public key authentication signs requests and responses as JSON Web Tokens (JWTs). Certificate-based and hybrid authentication options are also available. See Securing communication.
  • Fail-closed behavior: The request fails if your Callback Handler rejects it or does not respond in time, so the Co-signer does not sign without approval.
  • Enclave-protected enforcement: The Co-signer that enforces your Callback Handler’s decision runs inside a hardened enclave. See the API Co-signers Architecture Overview.

​
How it works

When a Policy rule designates an API user paired with the Co-signer as the signer or approver, the Co-signer calls your Callback Handler before it acts:
  1. Your application creates a transaction through the Fireblocks API.
  2. Fireblocks evaluates your Policy rules. If the designated signer is an API user paired with the Co-signer, the request is routed to the Co-signer.
  3. The Co-signer sends a request to your Callback Handler with the request details.
  4. Your Callback Handler runs your custom logic and responds with a CallbackResponse action.
  5. The Co-signer signs or approves the request only if your Callback Handler responds with APPROVE. A RETRY response tells the Co-signer to resend the request according to its retry policy. A REJECT response or a missing response causes the request to fail. See the Callback Handler response object for response behavior and timing.
The flow is fail-closed by default because the Co-signer requires approval from your Callback Handler before it signs.
Cold workspacesIn cold workspaces, transaction signing is performed offline using the cold mobile app, so the API Co-signer never signs. The Co-signer still participates in the approval stage, and a Callback Handler can be configured for API users paired with it in that role:
  • Non-Signing Admin — transaction approvals and configuration change approvals.
  • Approver — transaction approvals.
Pair a Non-Signing Admin or Approver API user with the Co-signer, then configure a Callback Handler for that user to apply your approval logic to incoming requests.

​
Securing communication between the Co-signer and the Callback Handler

When configuring the Callback Handler for an API user paired with the Co-signer, you select how the communication between the Co-signer (which acts as a client) and the Callback Handler server is authenticated. Fireblocks supports public key, certificate-based, and hybrid authentication modes. For the full list of authentication options and their configuration steps, see Securing communication.

​
Best practices

  • Isolate the Callback Handler. Run it on a server separate from the Co-signer instance, and restrict both the Co-signer and the Callback Handler from open connections to external locations unless necessary. This minimizes the attack surface around your signing logic.
  • Respond quickly and reliably. MPC signing does not begin until your Callback Handler approves the request. If your logic needs more time, respond with RETRY as described in the Callback Handler response object.
  • Handle retries idempotently. Retried requests are sent with identical parameters, so make sure your Callback Handler deals with the asynchronous nature of the calls and does not treat a retry as a new request.
  • Use HTTPS in production. Serve the Callback Handler with a valid TLS certificate from a trusted Certificate Authority (CA).
  • Start from the boilerplate. The Plugin-based Callback Handler provides a pre-built server application so you can focus on your custom logic instead of server development.
  • Harden the server itself. Operational hardening of the Callback Handler machine, such as access restrictions and monitoring, is covered in the API Co-signer Security Checklist.