Firebase integration

Configure Firebase Authentication as an auth provider so your Firebase users can connect to CloudSignal MQTT with credentials derived from their Firebase ID token. Use this when your app already authenticates users via Firebase Auth.

Prerequisites

A Firebase project with authentication enabled
A CloudSignal account with API keys
Firebase Admin SDK credentials (service account)

Configuration

Get Firebase project ID

Go to Firebase Console
Select your project
Go to Project Settings (gear icon)
Copy the Project ID

Add Firebase provider in CloudSignal

Go to CloudSignal Dashboard
Navigate to Connections → Auth Providers
Click Add Provider
Select Firebase
Enter your configuration:

Field	Value
Name	A friendly name (for example, "Production Firebase")
Project ID	Your Firebase project ID

Click Save

Test the integration

Exchange a Firebase ID token:

curl -X POST https://auth.cloudsignal.app/v2/tokens/exchange \
  -H "Authorization: Bearer YOUR_CLOUDSIGNAL_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "firebase",
    "token": "YOUR_FIREBASE_ID_TOKEN"
  }'

Implementation

React/Next.js example

import { initializeApp } from 'firebase/app';
import { getAuth } from 'firebase/auth';
import CloudSignal from '@cloudsignal/mqtt-client';

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
};

const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

// Connect to MQTT using the Firebase ID token
async function connectMqtt() {
  const user = auth.currentUser;

  if (!user) {
    throw new Error('User not authenticated');
  }

  // Get Firebase ID token
  const idToken = await user.getIdToken();

  const client = new CloudSignal();

  // The SDK exchanges the Firebase ID token for MQTT credentials
  await client.connectWithToken({
    host: 'wss://connect.cloudsignal.app:18885/',
    organizationId: 'org_k7xm4pqr2n5t',
    provider: 'firebase',
    externalToken: idToken,
  });

  client.setOnlineCallback(() => {
    console.log('Connected to MQTT');
  });

  return client;
}

API route (Next.js)

// app/api/mqtt-credentials/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { firebaseToken } = await request.json();

  const response = await fetch('https://auth.cloudsignal.app/v2/tokens/exchange', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CLOUDSIGNAL_SK}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      provider: 'firebase',
      token: firebaseToken
    })
  });

  const credentials = await response.json();
  return NextResponse.json(credentials);
}

React Native / Expo example

import auth from '@react-native-firebase/auth';
import CloudSignal from '@cloudsignal/mqtt-client';

async function connectToMqtt() {
  const currentUser = auth().currentUser;

  if (!currentUser) {
    throw new Error('Not logged in');
  }

  // Get Firebase ID token
  const idToken = await currentUser.getIdToken();

  const client = new CloudSignal({ preset: 'mobile' });

  // The SDK exchanges the Firebase ID token for MQTT credentials
  await client.connectWithToken({
    host: 'wss://connect.cloudsignal.app:18885/',
    organizationId: 'org_k7xm4pqr2n5t',
    provider: 'firebase',
    externalToken: idToken,
  });

  return client;
}

Flutter example

import 'package:firebase_auth/firebase_auth.dart';
import 'package:mqtt_client/mqtt_client.dart';
import 'package:mqtt_client/mqtt_browser_client.dart';

class MqttService {
  MqttBrowserClient? client;

  Future<void> connect() async {
    // Get Firebase ID token
    final user = FirebaseAuth.instance.currentUser;
    if (user == null) throw Exception('Not authenticated');

    final idToken = await user.getIdToken();

    // Exchange for MQTT credentials
    final response = await http.post(
      Uri.parse('https://your-api.com/mqtt-credentials'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'firebaseToken': idToken}),
    );

    final credentials = jsonDecode(response.body);

    // Connect to MQTT
    client = MqttBrowserClient(
      'wss://connect.cloudsignal.app:18885/',
      'flutter_client'
    );

    client!.setProtocolV311();

    await client!.connect(
      credentials['mqtt_username'],
      credentials['mqtt_password']
    );
  }
}

Handling token refresh

Firebase ID tokens expire after 1 hour. Handle this gracefully:

import { getAuth, onIdTokenChanged } from 'firebase/auth';
import CloudSignal from '@cloudsignal/mqtt-client';

const auth = getAuth();
let mqttClient: CloudSignal | null = null;

// Listen for Firebase token changes and re-exchange for fresh MQTT credentials
onIdTokenChanged(auth, async (user) => {
  if (user && mqttClient) {
    // Get the refreshed Firebase ID token
    const idToken = await user.getIdToken();

    // Reconnect with the new token
    await mqttClient.disconnect();
    await mqttClient.connectWithToken({
      host: 'wss://connect.cloudsignal.app:18885/',
      organizationId: 'org_k7xm4pqr2n5t',
      provider: 'firebase',
      externalToken: idToken,
    });
  }
});

ACL rules for Firebase users

Create ACL rules that match Firebase user UIDs:

# User can only access their own topics
User Pattern: %
Topic: users/%u/#
Permission: pubsub

The MQTT username will be derived from the Firebase UID or email.

Troubleshooting

"Invalid token" error

Check	What to verify
Token freshness	Firebase ID tokens expire after 1 hour
Project ID	Must match your Firebase project exactly
Token type	Use `user.getIdToken()`, not custom tokens

"Provider not found" error

Check	What to verify
Provider enabled	Confirm the provider is enabled in CloudSignal
Provider name	Use `"provider": "firebase"` (lowercase)

"Token verification failed"

Check	What to verify
Firebase project status	Ensure Auth is enabled
Token format	Should be a valid JWT

Next steps

Auth0 integration - Same pattern with audience and domain
Token Exchange API reference - Full request and response details
ACL rules guide - Scope topics to the authenticated user

On this page