Learn more about the API Co-Signer Callback Handler here


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



When adding the Callback Handler URL to the Co-Signer, you should pass only the base URL + custom relative path.
The </v2/tx_sign_request> or </v2/config_change_sign_request> relative paths will be automatically added upon each request made by the Co-Signer.

For example if you exposed the Callback Handler URL in the following path:

You should configure the following URL in the Co-Signer: