API Passphrase Verification: Setup Guide and FAQ

November 17, 2026 at 12:31 PM

Why is BloFin requiring passphrase verification?

The passphrase provides an additional credential check alongside your API secret. This helps prevent unauthorized API access if your API key and secret are exposed without the passphrase.

The passphrase must match the one set when the API key was created.

Do I need to update my API integration?

No action is required if your integration already sends the correct passphrase for both REST and WebSocket authentication.

You need to update your integration if:

  • It does not send a passphrase.
  • It sends a passphrase for REST but not WebSocket, or the other way around.
  • You manually entered your API credentials into a third-party platform that does not support a passphrase.

The official BloFin Python SDK and MCP SDK have already sent the passphrase. Confirm that it is included in your configuration.

How do I add the passphrase to REST and WebSocket requests?

REST and WebSocket authentication are usually handled separately. Update both:

  1. Add the ACCESS-PASSPHRASE header to private REST requests.
  2. Add the passphrase field to the WebSocket login message.
  3. Use the passphrase set when the API key was created.
  4. Restart your integration.
  5. Test one private REST request and one WebSocket private-channel login.

Private REST requests should include:

ACCESS-KEY:         your API key
ACCESS-SIGN:        signature
ACCESS-TIMESTAMP:   timestamp in milliseconds
ACCESS-NONCE:       unique random string
ACCESS-PASSPHRASE:  the passphrase set when creating the API key

Only the verification requirement for ACCESS-PASSPHRASE is changing with this setup. The signing logic remains the same.

A WebSocket login message should include:

{"op": "login", "args": [{
    "apiKey": "your API key",
    "passphrase": "the Passphrase set when creating the API key",
    "timestamp": "timestamp in milliseconds",
    "sign": "signature (algorithm unchanged)",
    "nonce": "unique random string"
}]}

Does this change the signature algorithm?

No. The passphrase is sent as a separate field and is not included in the REST or WebSocket signature.

The following remain unchanged:

  • ACCESS-SIGN calculation
  • Prehash composition
  • HMAC-SHA256 and Base64 encoding
  • WebSocket login signing string
  • API key and secret
  • API permissions
  • IP allowlist

What should I do if I use a third-party platform?

If you manually entered your API credentials into a copy-trading platform, trading bot, terminal, or similar product:

  1. Find the passphrase field in the platform’s BloFin connection settings.
  2. Enter the passphrase set when the API key was created.
  3. Test the connection.

If there is no passphrase field, contact the platform to confirm when it will be added. The connection may stop working once passphrase verification becomes mandatory for the key.

API keys created through BloFin’s authorization flow are not included at this stage. A separate announcement will follow.

How do I troubleshoot a passphrase error?

First, make one private REST request and one WebSocket private-channel login. This helps identify which connection is not configured correctly.

Then check for:

  1. A missing ACCESS-PASSPHRASE header in REST requests.
  2. A missing passphrase field in the WebSocket login message.
  3. Typos, spaces, or line breaks.
  4. A passphrase belonging to a different API key.
  5. Production and demo credentials being mixed.
  6. Different values configured for REST and WebSocket.
  7. An incorrect value saved on a third-party platform.

A failed WebSocket verification returns a login failure event. Check the passphrase field in the login message.

Do not automatically retry failed verification requests. Repeated failures may temporarily rate-limit the API key.

What if I have lost my passphrase?

BloFin cannot retrieve or reset a lost passphrase. You will need to create a new API key:

  1. Create a new key and securely save its API key, secret, and passphrase.
  2. Apply the required permissions and IP allowlist.
  3. Replace all three credentials in your integration or third-party platform.
  4. Confirm that REST and WebSocket authentication both work.
  5. Delete the old API key.

Create and test the new key before deleting the old one to avoid an interruption.

Was this article helpful?