Overview

Re-enrolling an API user allows you to reconnect the user to your API Co-Signer server. You may need to do this when:

• You receive errors during the initial setup of the API Co-Signer server
• You pair an API user with a new or existing API Co-Signer instance
• You change the API Co-Signer Callback Handler configuration, such as switching the authentication method from certificate authentication to public key authentication (or vice versa)

Re-enrolling an API user

To re-enroll an API user:

1. In the Fireblocks Console, go to Settings  > Users.
2. Find the API user you want to re-enroll, then select More Actions (...) > Re-enroll API user.

This submits a request to the workspace Owner to approve re-enrolling the API user. After the Owner approves the request:

• If you're re-enrolling an API user due to receiving errors during the initial setup of the API Co-Signer server, or to pair the API user with a new or existing API Co-Signer instance, refer to the "Installing the API Co-Signer software without a Callback Handler" section for further instructions.
• If you're re-enrolling an API user due to changing the API Co-Signer Callback Handler configuration, refer to the "Pairing an API user with the API Co-Signer" section for further instructions.

After you pair the API user with the API Co-Signer, the Owner must approve the API Co-Signer's key shares to complete the process.

Troubleshooting API user re-enrollment

"Failed to pair device, HTTP status 500"

When this error occurs, the response looks similar to the one below.

customer_cosigner:26 INFO 10/05/2022 16:00:55,908 curl/curl_utils.cpp(237) fireblocks::common::curl::internal_request - Curl command to https://mobile-api.fireblocks.io/pair_device was executed sucessfully! Response Code 500
customer_cosigner:26 INFO 10/05/2022 16:00:55,908 curl/curl_utils.cpp(241) fireblocks::common::curl::internal_request - Consider internal error (500) to https://mobile-api.fireblocks.io/pair_device as a communication error, Attempt#2
FATAL 10/05/2022 16:00:56,409 main.cpp(566) std::__cxx11::string pair_device_and_get_access_token - Failed to pair device, HTTP status 500

This error response indicates that the API user was re-enrolled, but the pairing token for the user expired before it was entered. The pairing token is valid for one hour after you copy it from the Console.

To resolve this, you must re-enroll the API user and then retrieve a new pairing token from the Console. Remember, only Admin-level users can retrieve the pairing token.

"Failed with error SSL public key does not match pinned public key"

When this error occurs, it means the SSL certificate on the Callback Handler server doesn't match the certificate on the API Co-Signer. Typically, this means the certificate on the Callback Handler server was changed or expired.

To resolve this, you must re-enroll the API user and then fetch the updated SSL certificate from the Callback Handler.

To re-enroll the API user and fetch the updated SSL certificate:

1. Re-enroll the API user you want to have on the API Co-Signer.
2. Add the API user to the API Co-Signer server with the following command:

   ./cosigner add-user

3. In the Fireblocks Console, go to Settings  > Users, find the API user, and retrieve its pairing token.
4. Enter the API user's pairing token and fetch the updated certificate as described here.

After you complete the above, the workspace Owner receives a request to approve the API Co-Signer's key shares. After they approve the request, make sure the API Co-Signer can initiate and sign transactions.