API Authentication

The Fireblocks API uses an API key and a request-signing process to provide a highly secure communication protocol. You can create API keys through the Fireblocks Console or the API.

Create an API key in the Console

To create your first API key:

1. Generate an RSA 4096 private key and CSR file:
   bash

   openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr -subj '/O=<your_organization>'

2. In the Fireblocks Console, go to the Developer center's API users page.
3. Select Add API user.
4. Enter a display name for the API key (up to 30 characters) and select the appropriate role. Permissions follow the same user roles used for Console users.
5. Upload the CSR file you generated in step 1.
6. Select whether a Co-signer setup is required.
   1. If you're in a testnet workspace, you can connect to the Fireblocks Communal Test Co-signer.
   2. Only select First user on this machine if you're using the API user to install a new SGX Co-signer.
7. Select Add user.

After the required approval quorum is reached, the API key appears in the API users list. You can copy the API key from there by hovering your pointer over the value in the API User (ID) column.

Every request using this API key must follow the Fireblocks API authentication scheme.

Create an API key via the Fireblocks API

Complete step 1 from the Console procedure above to generate your RSA key and CSR file, then call the Create API Key endpoint to complete the API key creation operation.

API key management best practices

Your API credentials are a prime target for attackers. Fireblocks recommends following these best practices to work securely with our APIs.

Role-based access control

Provision each API user's role according to the principle of least privilege. Fireblocks supports multiple roles for role-based access control, and an API user can hold any one of them. Create separate API users to enforce duty separation and establish clear security boundaries.

👍

Best practice

Create at least two API users with distinct roles. For example, a Viewer role for read-only operations and a Signer role with transaction-signing capabilities.

Policy rules for API users

API users with transaction initiation and signing capabilities can execute transactions like any Console user. Create strong Policy rules to govern what transaction types these API users can conduct and from which accounts.

👍

Best practice

Limit API users to transact from a specific vault account and up to a defined amount. This blocks or flags transactions that exceed the pre-defined limits or originate from unauthorized accounts.

IP address allowlisting

Each API user can restrict API calls to specific IP addresses. If no IP addresses are allowlisted, the API accepts requests from any address. Explicitly allowlist only the IP addresses you expect to call the Fireblocks API.

🚧

Address format

Only /32 IP addresses are accepted. Do not enter addresses as a range of values.

Generating and storing RSA 4096 private keys

Each API user requires a public/private key pair to sign requests. Keep your fireblocks_secret.key file safe and secure at all times.

To protect your key pair:

• Generate a unique CSR file and key pair for each API user. This limits the blast radius if one user's keys are compromised.
• Generate the CSR file and key pair in an offline (air-gapped) environment for added security.
• Store fireblocks_secret.key in a hardened environment with advanced security controls such as multi-factor authentication and endpoint protection.

Storing API keys outside your codebase

Never embed API keys directly in code or commit them to your source tree. Keys embedded in code can be accidentally exposed, especially if you use a public source control system such as GitHub. Instead, store API keys in environment variables or in files outside your application's source tree.

Rotating secrets

Rotation works differently depending on the API user type:

• Fireblocks API users: Because authentication relies on a CSR and associated secret key, create a new API user to rotate credentials.
• Co-signers: Re-enroll the API user to obtain a new pairing token, then complete the pairing process to receive a new refresh token.
• Fireblocks Agent for KeyLink: Uses the pairing token, access token, and device. This user type does not hold MPC keys.

👍

Best practice

Before rotating, use the Get all API keys endpoint to list all API keys paired to a specific API Co-Signer.