Magic Links API

The Magic Links API extends the functionality of Spaces by allowing you to configure Session behavior for specific users. This includes authenticating users and restricting or enabling certain features, providing enhanced flexibility and control.

Magic links bypass Space authentication settings. This means users with a valid magic link can access private Spaces and are treated as “verified” users, similar to OAuth2 authentication methods like Google or GitHub.

Format

The Magic Links API leverages the widely-used JWT (JSON Web Token) format. This format enables you to generate as many magic links as needed without requiring requests to our server.

Usage

1. Generate a JWT containing the fields you want to include (space_id field is required).
2. Sign the JWT using your signing key (Magic Link key).
3. Use the generated JWT string by appending it as a magic_link query parameter to the Space URL it was configured for.

Example:

https://webfuse.com/+myspace/?magic_link=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Signing Key

A dedicated signing key is available in the Space settings API section, key type - Magic Link key.

Caution

When deleting or regenerating your signing key, all magic links that have already been issued will stop working. Make sure to generate new magic links.

Features

Name

You can specify a name for a user in the magic link. This name will appear in the Session interface and be visible to all participants.

Email

Specify an email for a user through the magic link for additional Session context and functionality.

URLs

Magic links can be configured to automatically open multiple tabs, with the last tab activated.

User ID

You can specify a user ID for a user in the magic link. This user ID will be used to identify the user in the Session. The user ID needs to be present in the Space members list.

Revocation (coming soon)

A feature to revoke magic links is under development.

Example

Here’s an example of how to generate and use a magic link:

Python

import jwt  # Install using 'pip install pyjwt'
import datetime

# Define your signing key

MAGIC_Link_Key = "your_secret_key"

# Define the payload for the JWT

payload = {
    "space_id": "1",  # Required field
    "name": "John Doe",
    "email": "johndoe@example.com",
    "can_host": True,
    "user_id": 1,
    "urls": ["https://example.com", "https://wikipedia.org"],
    "exp": datetime.datetime.utcnow() + datetime.timedelta(days=7)
}

# Generate the JWT

magic_link = jwt.encode(payload, MAGIC_Link_Key, algorithm="HS256")

# Use the generated magic link in your Space URL

space_url = f"https://webfuse.com/+myspace/?magic_link={magic_link}"
print(f"Magic Link: {space_url}")

NodeJS

const jwt = require('jsonwebtoken');

// Define your signing key
const MAGIC_Link_Key = "your_secret_key";

// Define the payload for the JWT
const payload = {
    "space_id": "1",  // Required field
    "name": "John Doe",
    "email": "johndoe@example.com",
    "can_host": true,
    "urls": ["https://example.com", "https://wikipedia.org"],
    "exp": Math.floor(Date.now() / 1000) + (7 * 24 * 60 * 60)
};

// Generate the JWT
const magic_link = jwt.sign(payload, MAGIC_Link_Key, { algorithm: 'HS256' });

// Use the generated magic link in your Space URL
const space_url = `https://webfuse.com/+myspace/?magic_link=${magic_link}`;
console.log(`Magic Link: ${space_url}`);

PHP

<?php
require_once 'vendor/autoload.php'; // Requires firebase/php-jwt package
use \Firebase\JWT\JWT;

// Define your signing key
$MAGIC_Link_Key = "your_secret_key";

// Define the payload for the JWT
$payload = array(
    "space_id" => "1",  // Required field
    "name" => "John Doe",
    "email" => "johndoe@example.com",
    "can_host" => true,
    "urls" => ["https://example.com", "https://wikipedia.org"],
    "exp" => time() + (7 * 24 * 60 * 60)  // 7 days from now
);

// Generate the JWT
$magic_link = JWT::encode($payload, $MAGIC_Link_Key, 'HS256');

// Use the generated magic link in your Space URL
$space_url = "https://webfuse.com/+myspace/?magic_link=" . $magic_link;
echo "Magic Link: " . $space_url;

Go

package main

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt"
)

func main() {
    // Define your signing key
    magicLinkKey := []byte("your_secret_key")

    // Define the payload for the JWT
    payload := jwt.MapClaims{
        "space_id":  "1", // Required field
        "name":      "John Doe",
        "email":     "johndoe@example.com",
        "can_host":  true,
        "urls":      []string{"https://example.com", "https://wikipedia.org"},
        "exp":       time.Now().Add(time.Hour * 24 * 7).Unix(),
    }

    // Generate the JWT
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, payload)
    magicLink, err := token.SignedString(magicLinkKey)
    if err != nil {
        panic(err)
    }

    // Use the generated magic link in your Space URL
    spaceURL := fmt.Sprintf("https://webfuse.com/+myspace/?magic_link=%s", magicLink)
    fmt.Printf("Magic Link: %s\n", spaceURL)
}

This above code generates a JWT using the specified payload and secret key, then appends it to the Space URL as a query parameter.