WebSocket Authentication

FortiBlox WebSocket requires API key authentication for all connections. Choose the authentication method that works best for your platform.

Authentication Methods

Query Parameter (Recommended for Browsers)

Pass your API key as a URL query parameter:

const ws = new WebSocket(
  'wss://nexus.fortiblox.com/geyser/ws?api-key=fbx_YOUR_KEY_HERE'
);

Pros:

• ✅ Works in all browsers (native WebSocket API)
• ✅ No special libraries needed
• ✅ Simple to implement

Cons:

• ⚠️ API key visible in URL (use HTTPS)
• ⚠️ May appear in logs
• ⚠️ Not ideal for production (use RPC Proxy instead)

X-API-Key Header (Recommended for Servers)

Pass your API key in the HTTP upgrade request header:

const WebSocket = require('ws');

const ws = new WebSocket('wss://nexus.fortiblox.com/geyser/ws', {
  headers: {
    'X-API-Key': 'fbx_YOUR_KEY_HERE'
  }
});

import websockets

async def connect():
    uri = 'wss://nexus.fortiblox.com/geyser/ws'
    headers = {
        'X-API-Key': 'fbx_YOUR_KEY_HERE'
    }

    async with websockets.connect(uri, extra_headers=headers) as ws:
        # Connected
        pass

asyncio.run(connect())

package main

import (
    "github.com/gorilla/websocket"
    "net/http"
)

func main() {
    headers := http.Header{}
    headers.Add("X-API-Key", "fbx_YOUR_KEY_HERE")

    conn, _, err := websocket.DefaultDialer.Dial(
        "wss://nexus.fortiblox.com/geyser/ws",
        headers,
    )
    if err != nil {
        panic(err)
    }
    defer conn.Close()
}

Pros:

• ✅ More secure (not in URL)
• ✅ Standard HTTP header
• ✅ Won't appear in URL logs

Cons:

• ❌ Not supported by browser WebSocket API
• ⚠️ Requires WebSocket library with header support

Authorization Bearer Header

Alternative header-based authentication:

const ws = new WebSocket('wss://nexus.fortiblox.com/geyser/ws', {
  headers: {
    'Authorization': 'Bearer fbx_YOUR_KEY_HERE'
  }
});

This is equivalent to X-API-Key header and follows OAuth conventions.

Environment-Specific Best Practices

Browser Applications

Development:

// OK for local testing
const ws = new WebSocket(
  `wss://nexus.fortiblox.com/geyser/ws?api-key=${process.env.REACT_APP_API_KEY}`
);

Production:

// Use RPC Proxy instead
const ws = new WebSocket('wss://your-proxy.com/ws');
// Proxy adds API key server-side

Set up RPC Proxy →

Node.js Applications

Using environment variables:

// .env file
FORTIBLOX_API_KEY=fbx_YOUR_KEY_HERE

// app.js
require('dotenv').config();
const apiKey = process.env.FORTIBLOX_API_KEY;

const ws = new WebSocket('wss://nexus.fortiblox.com/geyser/ws', {
  headers: { 'X-API-Key': apiKey }
});

Using secrets manager:

const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

async function getApiKey() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'fortiblox-api-key'
  }).promise();

  return JSON.parse(secret.SecretString).apiKey;
}

const apiKey = await getApiKey();
const ws = new WebSocket('wss://nexus.fortiblox.com/geyser/ws', {
  headers: { 'X-API-Key': apiKey }
});

Python Applications

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('FORTIBLOX_API_KEY')
uri = f'wss://nexus.fortiblox.com/geyser/ws?api-key={api_key}'

Docker Containers

Pass API key as environment variable:

docker run -e FORTIBLOX_API_KEY=fbx_YOUR_KEY_HERE your-app

# Dockerfile
ENV FORTIBLOX_API_KEY=""

# Use build arg for security
ARG API_KEY
ENV FORTIBLOX_API_KEY=$API_KEY

API Key Scopes

Your API key must have the following scope for WebSocket access:

geyser:stream

All tiers (including Free) include this scope by default when creating a new API key.

Verify Your Key's Scopes

1. Log in to Nexus Dashboard
2. Navigate to API Keys
3. View your key details
4. Check Scopes section

If geyser:stream is missing, regenerate your API key.

Connection Limits

Each tier has concurrent WebSocket connection limits:

Exceeding this limit will result in:

• HTTP 429 (Too Many Requests)
• Oldest connection may be dropped
• New connection rejected

Security Best Practices

1. Never Hardcode API Keys

❌ Bad:

const ws = new WebSocket(
  'wss://nexus.fortiblox.com/geyser/ws?api-key=fbx_1234567890abcdef'
);

✅ Good:

const apiKey = process.env.FORTIBLOX_API_KEY;
const ws = new WebSocket(
  `wss://nexus.fortiblox.com/geyser/ws?api-key=${apiKey}`
);

2. Use Environment Variables

# .env
FORTIBLOX_API_KEY=fbx_YOUR_KEY_HERE

# Add .env to .gitignore
echo ".env" >> .gitignore

3. Rotate Keys Regularly

1. Generate a new API key
2. Update your application configuration
3. Test the new key
4. Revoke the old key

4. Use Different Keys Per Environment

# Development
FORTIBLOX_API_KEY=fbx_test_DEV_KEY_HERE

# Production
FORTIBLOX_API_KEY=fbx_PROD_KEY_HERE

5. Restrict Key Access

In the Nexus Dashboard, configure:

• IP Restrictions - Limit which IPs can use the key
• Domain Restrictions - Limit which domains can use the key
• Network Restrictions - Mainnet, devnet, or testnet only

Learn more about access control →

Troubleshooting

401 Unauthorized

Symptoms:

• Connection immediately closes
• Error: "Unauthorized"

Solutions:

1. Verify API key is correct
2. Check key status is "Active"
3. Ensure key hasn't expired
4. Remove any spaces/newlines from key

403 Forbidden

Symptoms:

• Connection closes after authentication
• Error: "Missing geyser:stream scope"

Solutions:

1. Check key has geyser:stream scope
2. Regenerate key if scope is missing
3. Verify key permissions in dashboard

429 Too Many Requests

Symptoms:

• New connections rejected
• Error: "Connection limit exceeded"

Solutions:

1. Close unused WebSocket connections
2. Check your tier's connection limit
3. Implement connection pooling
4. Upgrade to higher tier if needed

Connection Timeout

Symptoms:

• Connection hangs during upgrade
• No error message

Solutions:

1. Check network connectivity
2. Verify firewall allows WebSocket (port 443)
3. Test with: wscat -c wss://nexus.fortiblox.com/geyser/ws?api-key=YOUR_KEY
4. Check status page

Testing Your Connection

Use wscat to test WebSocket authentication:

# Install wscat
npm install -g wscat

# Test with query parameter
wscat -c "wss://nexus.fortiblox.com/geyser/ws?api-key=fbx_YOUR_KEY"

# Test with header
wscat -c wss://nexus.fortiblox.com/geyser/ws -H "X-API-Key: fbx_YOUR_KEY"

Expected output:

Connected (press CTRL+C to quit)
>

Next Steps