Configuration Approval Callback
POST /v2/config_change_sign_request
This request expects a CallbackResponse object from the callback handler. If the callback handler does not respond within 30 seconds, Fireblocks fails the request. If your callback handler can’t respond within 30 seconds, you can use the retry mechanism by responding with RETRY.
Request parameters
string
A unique identifier of this request. It must be returned in the response.
string
(Optional) The Fireblocks API user ID associated with the cosigner device that’s signing this approval.
string
The type of configuration request. See Configuration types for the full list of values and their fields.
object
Additional information about the request. The shape depends on
type. See Configuration types.Configuration types
Each type below lists the fields Fireblocks sends inextraInfo for that specific configuration change.
Wallets and external accounts
UNMANAGED_WALLET
An event that involves address whitelisting. This type also covers theUNMANAGED_V2 internal request type — both surface as UNMANAGED_WALLET in the callback.
string
INTERNAL - Internal Wallets are addresses you control outside your Fireblocks workspace. Internal addresses display their current balance and are included in your workspace’s total billable address count.EXTERNAL - External Wallets are addresses managed by your clients and counterparties.CONTRACT - Contract Wallets are addresses of smart contracts you want to interact with. Currently, this only applies to smart contracts on EVM-compatible blockchains.string
The name of the internal, external, or contract wallet you want to approve adding an address to.
string
The ID of the internal, external, or contract wallet that you want to approve adding an address to.
string
The ID of the asset to add to this wallet. Use GET supported assets request to retrieve more information about an asset.
string
The asset deposit address requested to be added to the wallet.
string
Destination address tag for Ripple; destination memo for EOS, Stellar, Hedera, & DigitalBits; destination note for Algorand; bank transfer description for fiat providers.Note: For Stellar, the memo must be a string representation of an integer between “0” and “2147483647”. Setting the memo to other values for Stellar assets will result in a failed request with an error message.
object
(Optional) Extra address metadata, present only when the whitelisting request originated from certain workspace flows.
UNMANAGED_DAPP
An event that involves adding an unmanaged dApp connection to your workspace.string
The name of the dApp connection’s wallet container.
string
The ID of the dApp connection’s wallet container.
string
The name of the dApp.
string
The URL of the dApp.
string
The dApp connection subtype.
EXCHANGE, FIAT_ACCOUNT, and CONNECTED_ACCOUNT
An event that involves adding an exchange account, fiat account, or connected account to your workspace. All three types share the same fields.string
The specific exchange, fiat account, or connected account provider.
string
The account’s name.
string
The account’s ID.
string
The third-party service’s API key. Blank for certain provider subtypes.
string
(Optional) A JSON-formatted “key”:“value” string, where “key” is an asset symbol and “value” is its address. There can be multiple entries in the JSON. Only populated for
FIAT_ACCOUNT. Use supported_assets to retrieve asset symbols.Users and devices
ADD_USER
An event that involves adding a user to your workspace.string
The UUID of the user being added.
string
The type of the added user:
CONSOLE or API.string
The user’s assigned role.
string
The user’s first and last name.
string
The user’s email address.
DELETE_USER
An event that involves removing a user from your workspace.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
string
The ID of the user being removed.
string
The user’s first name.
string
The user’s last name.
string
The user’s email address.
string
The user’s role.
string
A newline-separated list of alerts related to deleting this user (for example, pending requests or owned resources), if any.
EDIT_USER_INFO
An event that involves editing a user’s name, email, or role.string
The user’s first name before the change.
string
The user’s last name before the change.
string
The user’s email before the change.
string
The user’s role before the change.
string
The requested first name.
string
The requested last name.
string
The requested email.
string
The requested role.
RE_ENROLL_DEVICE
An event where an admin re-enrolls a mobile device for one of the users. UnlikeADD_USER, this type has no CONSOLE/API field: the role value here is deliberately stripped of the API USER: prefix, so you can’t recover whether the user is a console or API user from this payload.
string
The UUID of the user whose device is being reset.
string
The user’s role, without any console/API user prefix.
string
The user’s first and last name.
string
The user’s email address.
Cosigner and device pairing
COSIGNER_CHANGE_CALLBACK and PAIR_VIRTUAL_DEVICE
COSIGNER_CHANGE_CALLBACK changes the callback configuration (URL, certificate, JWT public key) of a device that’s already paired. PAIR_VIRTUAL_DEVICE pairs a new virtual (non-mobile) device using a pairing token.
string
The ID of the user who initiated the request.
string
The workspace ID.
string
The ID of the API user being paired.
string
The type of the paired user:
CONSOLE or API.string
The paired user’s first name.
string
The paired user’s role, including any console/API user prefix.
string
PAIR_VIRTUAL_DEVICE only
Always
null in this payload for both types. The actual pairing token is generated after approval and delivered separately.string
Your customer server URL to pair with.
string
Your customer server certificate.
string
Your customer JWT public key.
string
The physical device identifier.
string
COSIGNER_CHANGE_CALLBACK only
The device identifier.
string
Always
null in this payload for both types. Use the callback’s top-level requestId instead.Quorum and MPC configuration
CHANGE_QUORUM_THRESHOLD
An event where the admin updates the quorum threshold.number
The quorum threshold before the change.
number
The requested quorum threshold.
CONFIGURE_OWNER_IN_ADMIN_QUORUM
An event that changes whether the workspace owner counts toward the admin quorum.string
The ID of the user who initiated the request.
string
The workspace ID.
boolean
Whether the workspace owner counts toward the admin quorum.
SET_MPC_PROVISIONER
An event that designates a user as an MPC provisioner.string
Always
null in this payload — no producer currently populates it.boolean
Whether the user is set as an MPC provisioner.
IP allow list
ACTIVATE_IP_ALLOW_LIST
An event that turns the IP allow list on or off.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
boolean
Whether the IP allow list is being turned on or off.
string
The ID of the allow list rule.
ADD_IP_ADDRESS
An event that adds an IP address to the allow list.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
string
The label for this IP address entry.
string
The IP address being added.
string
The ID of this IP address entry.
string
The ID of the allow list rule.
string
When this entry was created.
string
When this entry was last updated.
DELETE_IP_ADDRESS
An event that removes an IP address from the allow list.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
string
The label for this IP address entry.
string
The IP address being removed.
string
The ID of this IP address entry.
string
The ID of the allow list rule.
string
When this entry was created.
string
When this entry was last updated.
string
The ID of the removed IP address.
UPDATE_IP_ADDRESS
An event that updates an existing IP address on the allow list.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
string
The current label for this IP address entry.
string
The requested label for this IP address entry.
string
The current IP address.
string
The requested IP address.
string
The ID of this IP address entry.
string
The ID of the allow list rule.
string
When this entry was created.
string
When this entry was last updated.
string
The ID of the updated IP address.
dApp connections and MEV protection
ENABLE_ONE_TIME_ADDRESS
An event which involves enabling a particular transaction to a one-time address in the workspace. This type has noextraInfo fields.
ENABLE_NON_EVM_DAPPS_CONNECTIONS
An event that enables dApp connections for non-EVM blockchains.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
ENABLE_MEV_DAPPS, DISABLE_MEV_DAPPS, ENABLE_MEV_API, and DISABLE_MEV_API
An event that enables or disables MEV protection for dApp connections or API-initiated transactions. All four types share the same fields.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
Fireblocks Network
ADD_NETWORK_CONNECTION
An event of adding a Fireblocks Network new connection.string
ID of network connection
string
Connection note
string
ID of local networkId
string
ID of the remote peer’s networkId
string
ID of remote peer tenantId
string
(Optional) JSON representation of routing policy object. Only included in the payload sent to the connection’s initiating tenant, not the receiving tenant.
SET_NETWORK_CONNECTION_ROUTING_POLICY
An event where the admin configures the routing policy for each network connection.string
ID of network connection
string
JSON representation of routing policy object
SET_NETWORK_ID_POLICY
An event of setting up the Fireblocks Network Network ID in case its profile is not discoverable.string
ID of networkID
string
JSON representation of routing policy object
Policies and approval groups
POLICY_APPROVAL
An event that involves updating the Transaction Authorization Policy.string
The ID of the user who originally edited the policy.
string
The name of the user who originally edited the policy.
string
The ID of the user who most recently edited the policy.
string
The name of the user who most recently edited the policy.
number
When the policy was edited, in Unix epoch time.
string
The ID of the user who initiated the request.
string
The name of the user who published the policy.
number
When the policy was published, in Unix epoch time.
number
(Optional) The number of allow rules in the policy.
number
(Optional) The number of block rules in the policy.
number
(Optional) The number of two-tier approval rules in the policy.
POLICY_CHANGE
An event that involves a pending edit to the Transaction Authorization Policy before it’s published.string
The ID of the user who originally edited the policy.
string
The name of the user who originally edited the policy.
string
The ID of the user who most recently edited the policy.
string
The name of the user who most recently edited the policy.
number
When the policy was edited, in Unix epoch time.
string
The ID of the user who initiated the request.
string
The name of the user who published the policy.
number
When the policy was published, in Unix epoch time.
object
(Optional) A summary of pending rule changes. Keys combine the rule type and verdict action (for example,
transferALLOWRules); values are display strings such as "3 Rules", not numeric counts. For a change spanning multiple policies, only the last policy’s counters are present.UPDATE_APPROVAL_GROUP_MAPPING
An event involving gathering a list of approvers for a particular admin operation.string
The first name of the user who initiated the request.
string
The last name of the user who initiated the request.
string
The admin operation type this approval group mapping applies to.
boolean
Whether the workspace owner must be included in the approval group.
string
The ID of the requested approval group.
number
The requested approval threshold.
string
The name of the requested approval group.
number
The number of members in the requested approval group.
number
When the request was created, in Unix epoch seconds.
USERS_GROUP_APPROVAL
An event that involves creating, editing, or deleting a user group in your workspace. The fields included depend on thesubType.
string
CREATE_USERS_GROUP, EDIT_USERS_GROUP, or DELETE_USERS_GROUP.string
The ID of the user who initiated the request.
string
The ID of the user group.
string
The name of the user group.
array
A list of the pending changes to the group.
array
A breakdown of the group’s members by role, plus a
total entry.string
(Optional) The requested group name. Included when
subType is EDIT_USERS_GROUP.array
(Optional) Users added to the group. Included when
subType is CREATE_USERS_GROUP or EDIT_USERS_GROUP.array
(Optional) Users removed from the group. Included when
subType is EDIT_USERS_GROUP. Same entry shape as addedUsers.array
(Optional) The IDs of the group’s members, as strings. Included when
subType is CREATE_USERS_GROUP or EDIT_USERS_GROUP.array
(Optional) The group’s members. Included when
subType is DELETE_USERS_GROUP. Same entry shape as addedUsers.REGISTER_EXTERNAL_KEYS_VALIDATOR_KEY
An event that registers a validator key for External Keys.string
The first name of the user who initiated the request.
string
The last name of the user who initiated the request.
string
The validator key being registered.
Automation rules
ADD_ACTIVE_AUTOMATION_RULE, ADD_INACTIVE_AUTOMATION_RULE, EDIT_AUTOMATION_RULE, DELETE_AUTOMATION_RULE, ACTIVATE_AUTOMATION_RULE, and DEACTIVATE_AUTOMATION_RULE
An event that adds, edits, deletes, activates, or deactivates an automation rule. All six types share the same fields.string
The ID of the user who initiated the request.
string
The workspace ID.
string
The configuration request type.
object
The full automation rule definition submitted for this change. Its schema is defined by the Automation Rules API.
Protected tags
EDIT_PROTECTED_TAG
An event that edits a protected tag.string
The ID of the protected tag.
string
The ID of the user who initiated the request.
object
The requested changes to the tag, as
newTag and previousTag objects with the same shape.DELETE_PROTECTED_TAG
An event that deletes a protected tag.string
The ID of the protected tag.
string
The ID of the user who initiated the request.
object
(Optional) The tag being deleted.
ATTACH_AND_DETACH_PROTECTED_TAGS
An event that attaches or detaches protected tags on one or more entities.string
The ID of the user who initiated the request.
array
(Optional) The entities being tagged or untagged.
array
(Optional) The tags being attached.
array
(Optional) The tags being detached. Same entry shape as
attachedTags.CREATE_ENTITIES_WITH_TAG_ATTACHMENTS
An event that creates entities with protected tags attached.string
The ID of the user who initiated the request.
string
The workspace ID.
array
(Optional) The IDs of the tags being attached.
number
(Optional) The type of entity being created:
1 for a vault account, 2 for a contact.number
(Optional) The number of entities being created.
number
(Optional) The highest existing vault account ID at request time, used as a floor for the newly created IDs. Only present when
entityType is 1 (vault account).object
(Optional) The tags being attached. Unlike
ATTACH_AND_DETACH_PROTECTED_TAGS, this field isn’t unwrapped to a plain array before being sent — the tag list is nested under values.