Skip to main content

Magic Links

Introduction​

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.

How to Use​

  1. Generate a JWT containing the fields you want to include (space_id field is required).
  2. Sign the JWT using your signing key (REST 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​

Space REST Key​

The Space REST Key is the default method for signing magic links.

Signing Key (Coming Soon)​

A dedicated signing key option is in development.

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.

A feature to revoke magic links is under development.

Usage Example​

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

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

# Define your signing key
REST_KEY = "your_secret_key"

# Define the payload for the JWT
payload = {
 "space_id": "1",
 "name": "John Doe",
 "email": "johndoe@example.com",
 "urls": ["https://example.com", "https://wikipedia.org"],
}

# Generate the JWT
magic_link = jwt.encode(payload, REST_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}")

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