Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Many organizations utilizing Fireblocks seek to integrate their workspace with third-party service providers such as accounting solutions, portfolio aggregation tools, trading platforms, and more. These providers can offer valuable insights, operational efficiencies, and additional functionality by integrating directly with a Fireblocks environment. However, since Fireblocks might not have native integrations with all these services, it is crucial to follow best practices to ensure that assets and data remain secure while maximizing the integration’s effectiveness. This guide is structured into two main sections:
  • For Fireblocks Clients: Provides step-by-step recommendations for securely integrating third-party service providers with your Fireblocks workspace, focusing on access control, API key management, and other security practices.
  • For Third-Party Service Providers: Offers guidance on how to securely connect with a client’s Fireblocks environment, emphasizing API key management, efficient data synchronization, and ensuring the client’s security requirements are met.
By addressing the specific concerns of both clients and providers, this guide aims to facilitate a smooth and secure integration process that benefits both parties.

​
Fireblocks Clients

​
Best Practices for Integration

​
1. Limit Access Levels

Ensure third-party providers are granted Viewer or Editor roles only—never Signer or Admin access. This principle applies to both API-based and UI-based integrations. Providing limited access minimizes risk exposure to your Fireblocks environment.

​
2. Secure API Key Management

If a third-party provider requires API access, the provider should handle key generation securely:
  • The provider should create their own RSA private key and a Certificate Signing Request (CSR). Only the CSR should be shared with you.
  • Never accept private keys over the internet.

​
Always ensure that the third-party provider generates their own RSA private key and shares only the Certificate Signing Request (CSR) with you. Never share your private key with the provider.

Refer to the Fireblocks API Key Management Documentation for details on secure key management.

​
3. Use Dedicated API Keys

Always generate a new API key specific to the third-party provider. Avoid reusing API keys from internal operations to mitigate risks and facilitate easier access management.

​
4. Whitelist Provider IP Addresses

To enhance security, whitelist the provider’s server IP addresses for the specific API key. This additional security measure helps ensure only authorized servers have access. More information can be found in the IP Whitelisting Documentation.

​
5. Initial Data Synchronization

For the first data sync, it’s best to manually share balance and address reports from the Fireblocks Console to avoid overloading the API and hitting rate limits.

​
6. Enable Webhook Notifications

To keep data synchronized without excessive API polling, enable webhooks to push real-time updates from Fireblocks to the provider. Visit the Webhook Configuration Guide for setup instructions.

​
7. Signing Transactions

If transaction signing is required, do not grant signing privileges directly to third-party providers. Use the Designated Signer feature and define a Policy. This approach maintains security by requiring your approval before any transaction is signed by the provider.

​
Third-Party Service Providers (Partners)

​
Best Practices for Integration

​
1. Understand Access Roles

When integrating with a Fireblocks client, expect to receive Viewer or Editor access only. Signer and Admin roles are not granted to maintain the client’s security. These roles should be sufficient for most integrations to view data and perform necessary actions. Learn more about Fireblocks user roles in the “Manage Users” guide.

​
2. Secure API Key Management

As a provider, you are responsible for securely generating and managing API keys:
  • Generate an RSA private key and CSR, sharing only the CSR with the Fireblocks client.
  • Never share private keys with clients or transmit them over the internet.
Consult the Fireblocks API Key Management Documentation for specific details on managing API keys securely.

​
Always generate the RSA private key yourself and share the Certificate Signing Request (CSR) with the client. Never request the client to provide their private key!

​
3. Request a Dedicated API Key

For every new client integration, request a separate API key. This practice allows clear separation of access per client and aids in efficient management and troubleshooting.

​
4. Provide IP Addresses for Whitelisting

To ensure your integration is secure, supply the client with your server’s IP addresses for whitelisting. This step helps secure API communication and restricts access to trusted IPs.

​
5. Efficient Data Synchronization

To avoid overloading the client’s Fireblocks API and ensure a smooth initial data sync, it’s recommended to start with balance and address reports shared directly from the Fireblocks Console. Coordinate with the client for a safe and efficient data transfer process.

​
6. Use Webhook Notifications

Reduce the need for frequent API polling by configuring webhooks that allow real-time updates from the Fireblocks client. This setup improves efficiency and ensures up-to-date data synchronization. Check the Webhook Configuration Guide for configuration steps.

​
7. Transaction Initiation Without Signing

If your integration requires initiating transactions, ask the client to configure your access according to their Policies. This will ensure that your API key can initiate transactions, but any signing or approval must be performed by the designated signer configured in the Policy. This designated signer should be the customer themselves!