Notice: Syft Router is in ALPHA. A major update will arrive mid-November — stay connected for updates.

Authentication

Understand guest vs authenticated access and implement authentication for your router. Learn about rate limits, token management, and access control patterns.

Authentication Overview

Syft LLM Routers offer flexible access control to accommodate different use cases. You can choose between open access for public services or token-based authentication for premium features and higher limits.

👥

Guest Mode

Open access with rate limits for public demos, free tier services, and educational content.

🔐

Authenticated Mode

Token-based access with user tracking, higher limits, and access to premium features.

Guest Mode Access

When to Use Guest Mode

Guest mode is perfect for scenarios where you want to provide immediate access without requiring users to sign up or authenticate:

This mode removes barriers to entry while still protecting your router from abuse through reasonable rate limits.

Guest Mode Limitations

To prevent abuse and ensure fair usage, guest mode comes with built-in restrictions that encourage users to authenticate for better service:

Rate Limits for Guest Users:
  • 10 requests per minute
  • 100 requests per day
  • Basic feature access only
  • No conversation history
  • No premium models

These limits are designed to allow meaningful testing while encouraging conversion to authenticated access for regular use.

Using Guest Mode

Guest access is as simple as making a direct API call. No tokens, no setup, no authentication headers required.

# Guest access - no auth headers needed
curl -X POST https://syftbox.net/api/v1/send/ \
  -H "Content-Type: application/json" \
  -H "x-syft-from: guest@syftbox.net" \
  -d '{
    "message": "What is machine learning?",
    "suffix-sender": "true",
    "timeout": "5000",
    "x-syft-url": "syft://your_email@example.com/app_data/my_router/rpc/chat"
  }'

Notice how clean this is - just include your message and routing information, and you're ready to go. The x-syft-url parameter tells the system which router should handle your request.

Authenticated Mode

For users who need more robust access or want to build production applications, authenticated mode provides significantly enhanced capabilities and fewer restrictions.

Benefits of Authentication

Higher Rate Limits

1000+ requests per day instead of the 100 guest limit

User Tracking

Conversation history and personalized preferences stored securely

Paid Services

Access to advanced models and premium router capabilities

Analytics

Detailed usage statistics and billing information

Authentication unlocks the full potential of the router system, including access to premium models and persistent conversation management.

Authentication Flow

1

Obtain Accounting Token

Getting started with authentication is straightforward. Users automatically receive their token when they first connect to the Syft LLM Router dashboard.

The token will be stored under ~/.syftbox/accounting_config.json for easy access by your applications.

2

Use Access Token

Once you have your token, using it is just a matter of adding the Authorization header to your requests. The system will automatically recognize you and apply your account's limits and preferences.

curl -X POST https://syftbox.net/api/v1/send/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "x-syft-from: user@example.com" \
  -d '{
    "message": "What is machine learning?",
    "suffix-sender": "true",
    "timeout": "5000",
    "x-syft-url": "syft://your_email@example.com/app_data/my_router/rpc/chat"
  }'

The key difference here is the Authorization: Bearer header containing your JWT token. This single addition transforms your request from guest access to full authenticated access with all its benefits.

Token Management

Token Storage

SyftBox automatically stores your authentication token in a secure configuration file:

# Location of token file
~/.syftbox/accounting_config.json

# Example token structure (truncated for security)
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_email": "user@example.com",
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-01T00:00:00Z"
}

Reading Tokens in Your Application

Here's how to read and use the stored token in your applications:

import json
import os
from pathlib import Path

def get_syftbox_token():
    """Read the SyftBox authentication token from config file."""
    config_path = Path.home() / ".syftbox" / "accounting_config.json"
    
    if not config_path.exists():
        raise FileNotFoundError("SyftBox token not found. Please log in to SyftBox first.")
    
    with open(config_path, 'r') as f:
        config = json.load(f)
    
    return config.get('token')

def make_authenticated_request(message, router_url):
    """Make an authenticated request to a Syft router."""
    import requests
    
    token = get_syftbox_token()
    
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
        "x-syft-from": "user@example.com"
    }
    
    data = {
        "message": message,
        "suffix-sender": "true",
        "x-syft-url": router_url
    }
    
    response = requests.post(
        "https://syftbox.net/api/v1/send/",
        headers=headers,
        json=data
    )
    
    return response.json()

# Usage example
result = make_authenticated_request(
    "Hello with authentication!",
    "syft://router_owner@example.com/app_data/my_router/rpc/chat"
)

Token Expiration and Renewal

SyftBox tokens have expiration dates for security. The system handles renewal automatically:

Rate Limiting Details

Platform Rate Limits

The SyftBox platform implements rate limiting at multiple levels:

Guest Users

  • 10 requests/minute
  • 100 requests/day
  • Basic endpoints only

Authenticated Users

  • Based on subscription tier
  • 1000+ requests/day
  • Access to premium endpoints

Per-Router Limits

  • Set by individual router owners
  • Can be more restrictive
  • Returned in response headers

Rate Limit Response Headers

When rate limits are hit, the system returns informative headers:

{
  "status": "success",
  "status_code": 429,
  "headers": {
    "x-ratelimit-limit": "100",
    "x-ratelimit-remaining": "0",
    "x-ratelimit-reset": "1642262400",
    "retry-after": "60"
  },
  "body": {
    "error": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 60 seconds.",
    "retry_after": 60
  }
}