Auth providers

Integrate external identity providers like Supabase, Firebase, and Auth0 with CloudSignal MQTT.

Auth providers let users authenticate with your existing identity system and exchange tokens for temporary CloudSignal MQTT credentials. Use this when you already manage user accounts in Supabase, Firebase, Auth0, or Clerk and want to skip a second credential system.

Native authentication is always available. Auth providers add additional authentication methods, they don't replace the built-in client credentials system.

How it works

Token exchange flow

User app

Identity provider

CloudSignal

MQTT broker

JWT token

Exchange JWT

MQTT credentials (temporary)

Connect with username + password

User logs in to your app via your auth provider
Your app calls CloudSignal's token exchange endpoint with the provider's JWT
CloudSignal validates the token and returns temporary MQTT credentials
User connects to MQTT with the temporary credentials

Supported providers

Supabase

Exchange Supabase JWTs for MQTT credentials

Firebase

Use Firebase Auth tokens with CloudSignal

Auth0

Integrate Auth0 authentication

Clerk

Authenticate via Clerk (dev + prod environments)

Token Exchange API

API reference for token exchange

Why use auth providers?

Single sign-on experience

Users log in once with their existing account.

Setup	Steps
Without auth providers	User logs in to your app, then needs separate MQTT credentials, and you manage two authentication systems
With auth providers	User logs in to your app, the app exchanges the token for MQTT credentials, and the user connects to MQTT

Automatic credential management

Property	Behavior
No password storage	Credentials are temporary and auto-generated
Automatic expiration	Tokens expire (default: 60 minutes)
User-scoped	Each user gets unique credentials tied to their identity

Simplified access control

Link MQTT permissions to your user's identity:

User: john@example.com (from Supabase)
  becomes
MQTT username: john_example_com@org-abc123
  matched by ACL on "john_example_com"
    Can publish to: users/john_example_com/#
    Can subscribe to: notifications/john_example_com/#

Quick start

1. Configure auth provider

Go to Connections → Auth Providers → Add Provider.

Select your provider and enter the required configuration:

Provider	Required config
Supabase	Project URL, JWT secret
Firebase	Project ID
Auth0	Domain, audience
Clerk	Dev and/or prod frontend API

2. Test token exchange

Use the API to exchange a token:

curl -X POST https://api.cloudsignal.io/v2/tokens/exchange \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "supabase",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Response:

{
  "mqtt_username": "user123@a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mqtt_password": "temp_password_xyz",
  "expires_at": "2024-01-15T13:00:00Z",
  "expires_in": 3600
}

3. Connect to MQTT

Use the returned credentials:

const mqtt = require('mqtt');

// Exchange token first
const credentials = await exchangeToken(supabaseSession.access_token);

// Connect with temporary credentials
const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: credentials.mqtt_username,
  password: credentials.mqtt_password
});

Best practices

Refresh tokens before expiry

// Track credential expiry
let mqttCredentials = null;
let expiresAt = null;

async function getCredentials() {
  // Refresh 5 minutes before expiry
  const refreshBuffer = 5 * 60 * 1000;

  if (!mqttCredentials || Date.now() > expiresAt - refreshBuffer) {
    const response = await exchangeToken(getAuthToken());
    mqttCredentials = response;
    expiresAt = new Date(response.expires_at).getTime();
  }

  return mqttCredentials;
}

Handle reconnection

client.on('close', async () => {
  // Get fresh credentials on reconnect
  const credentials = await getCredentials();
  client.options.username = credentials.mqtt_username;
  client.options.password = credentials.mqtt_password;
});

User-scoped ACL rules

Create ACL rules that leverage the user identity:

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

The %u substitutes the username, so john_doe can only access users/john_doe/#.

Next steps

Set up Supabase - JWT secret-based exchange
Set up Firebase - Project ID-based exchange
Set up Auth0 - Domain + audience exchange
Set up Clerk - Dev and production environments
Token Exchange API - Full API reference

Supabase

Firebase

Auth0

Clerk

Token Exchange API

On this page