Isometrik Docs

Authentication

Isometrik uses access tokens to authenticate participants joining rooms. These tokens are JSON Web Tokens (JWTs) that contain participant information and permissions.

Overview

Access tokens are generated server-side using your API secret and contain claims about the participant's identity, the room they're joining, and what permissions they have. This ensures that only authorized users can join rooms and perform actions.

Token Structure

An Isometrik access token contains the following claims:

  • iss: Your API key (issuer)
  • sub: Participant identity (unique identifier)
  • room: Room name or ID
  • exp: Token expiration timestamp
  • permissions: Participant permissions (canPublish, canSubscribe, etc.)

Generating Tokens

Server-side (Recommended)

Always generate tokens on your server to keep your API secret secure:

import { IsometrikClient } from '@isometrik/client';

const client = new IsometrikClient({
  apiKey: process.env.ISOMETRIK_API_KEY,
  apiSecret: process.env.ISOMETRIK_API_SECRET
});

// Generate token for a participant
app.post('/api/token', async (req, res) => {
  const { roomName, participantName } = req.body;

  const token = await client.tokens.create({
    roomId: roomName,
    participantName: participantName,
    permissions: {
      canPublish: true,
      canSubscribe: true,
      canUpdateMetadata: true
    },
    expiresIn: '1h'
  });

  res.json({ token });
});

Python Example

from isometrik import IsometrikClient
from flask import Flask, request, jsonify

app = Flask(__name__)
client = IsometrikClient(
    api_key=os.getenv('ISOMETRIK_API_KEY'),
    api_secret=os.getenv('ISOMETRIK_API_SECRET')
)

@app.route('/api/token', methods=['POST'])
def create_token():
    data = request.json
    token = client.tokens.create(
        room_id=data['roomName'],
        participant_name=data['participantName'],
        permissions={
            'can_publish': True,
            'can_subscribe': True,
            'can_update_metadata': True
        },
        expires_in='1h'
    )
    return jsonify({'token': token})

Permissions

Tokens can include various permissions to control what participants can do:

  • canPublish: Allow publishing audio/video tracks
  • canSubscribe: Allow subscribing to other participants' tracks
  • canUpdateMetadata: Allow updating participant metadata
  • canUpdateRoom: Allow updating room settings
  • canRemoveParticipants: Allow removing other participants

Token Expiration

Tokens should have a reasonable expiration time. For long-lived sessions, implement token refresh:

// Client-side: Refresh token before expiration
room.on('tokenExpiring', async () => {
  const newToken = await fetch('/api/token', {
    method: 'POST',
    body: JSON.stringify({
      roomName: room.name,
      participantName: room.localParticipant.identity
    })
  }).then(r => r.json());

  await room.updateToken(newToken.token);
});

Security Best Practices

  • Never expose your API secret in client-side code
  • Always validate user identity before generating tokens
  • Use short token expiration times (1-6 hours)
  • Implement token refresh for long sessions
  • Use HTTPS for all token generation endpoints
  • Validate room names and participant identities

Next Steps