Authentication

Overview

SuperBox uses Firebase Authentication with JWT (JSON Web Tokens) for secure API access. All authenticated endpoints require a valid Bearer token in the Authorization header.

Authentication Method

Firebase JWT Bearer Token Authentication

Getting Your API Token

Create an Account

Google

GitHub

Email

Email/Password

Navigate to Settings

Go to your Profile Settings page.

Generate API Token

Click “Generate API Token” to create a new authentication token.

This token will only be shown once. Store it securely!

Copy and Store

Copy your token and store it in a secure location like:

Environment variables
Secure password manager
Encrypted configuration file

Never commit tokens to version control or share them publicly.

Using Your Token

Environment Variable (Recommended)

Store your token in an environment variable:

export SUPERBOX_API_TOKEN="your_firebase_jwt_token_here"

Then reference it in your code:

curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

const token = process.env.SUPERBOX_API_TOKEN;

const response = await fetch("https://api.superbox.ai/api/v1/servers", {
  headers: {
 Authorization: `Bearer ${token}`,
 "Content-Type": "application/json",
  },
});

import os
import requests

token = os.getenv('SUPERBOX_API_TOKEN')
headers = {
 'Authorization': f'Bearer {token}',
 'Content-Type': 'application/json'
}

response = requests.get(
 'https://api.superbox.ai/api/v1/servers',
 headers=headers
)

Direct Usage

For testing or development, you can use the token directly:

curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5..."

const response = await fetch("https://api.superbox.ai/api/v1/servers", {
  headers: {
 Authorization: "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5...",
 "Content-Type": "application/json",
  },
});

headers = {
 'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5...',
 'Content-Type': 'application/json'
}

response = requests.get(
 'https://api.superbox.ai/api/v1/servers',
 headers=headers
)

Authentication Flow

Token Validation

When you make an authenticated request, the API validates your token:

Extract Token

API extracts the Bearer token from the Authorization header

Verify Signature

Token signature is verified using Firebase public keys

Check Expiration

Token expiration time is checked

Extract Claims

User ID and other claims are extracted from the token

Authorize Request

User permissions are checked for the requested resource

Token Structure

Firebase JWT tokens contain three parts separated by dots:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5...  (Header)
.
eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20v...  (Payload)
.
Signature_Hash_Value...  (Signature)

Token Payload Example

{
  "iss": "https://securetoken.google.com/superbox-project",
  "aud": "superbox-project",
  "auth_time": 1702123456,
  "user_id": "abc123def456",
  "sub": "abc123def456",
  "iat": 1702123456,
  "exp": 1702127056,
  "email": "user@example.com",
  "email_verified": true,
  "firebase": {
 "identities": {
"google.com": ["123456789"],
"email": ["user@example.com"]
 },
 "sign_in_provider": "google.com"
  }
}

string

Unique user identifier

string

User’s email address

integer

Token expiration timestamp (Unix time)

integer

Token issued at timestamp (Unix time)

Token Expiration

Token Lifetime

Firebase tokens expire after 1 hour (3600 seconds)

When a token expires, you’ll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
 "code": "INVALID_TOKEN",
 "message": "Authentication token has expired",
 "details": {
"expiredAt": "2025-12-09T11:30:00Z"
 }
  }
}

Automatic Token Refresh

The SuperBox frontend automatically refreshes tokens before they expire. For API clients, implement token refresh logic:

let token = await getFirebaseToken();
let tokenExpiry = getTokenExpiry(token);

async function makeRequest(url, options = {}) {
// Refresh if token expires in < 5 minutes
if (Date.now() > tokenExpiry - 5 * 60 * 1000) {
token = await refreshFirebaseToken();
tokenExpiry = getTokenExpiry(token);
}

return fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${token}`
}
});
}

import time
import jwt
from datetime import datetime, timedelta

class SuperBoxClient:
 def __init__(self, token):
  self.token = token
  self.token_expiry = self._get_token_expiry()

 def _get_token_expiry(self):
  decoded = jwt.decode(self.token, options={"verify_signature": False})
  return datetime.fromtimestamp(decoded['exp'])

 def _should_refresh(self):
  # Refresh if token expires in < 5 minutes
  return datetime.now() > self.token_expiry - timedelta(minutes=5)

 def make_request(self, url, **kwargs):
  if self._should_refresh():
self.token = self._refresh_token()
self.token_expiry = self._get_token_expiry()

  headers = kwargs.get('headers', {})
  headers['Authorization'] = f'Bearer {self.token}'
  kwargs['headers'] = headers

  return requests.request(**kwargs)

Public vs Authenticated Endpoints

Public Endpoints
Authenticated Endpoints

These endpoints don’t require authentication:

public

List all servers (read-only)

public

Get server details (read-only)

Public endpoints have stricter rate limits (100 req/hour)

These endpoints require a valid Bearer token:

authenticated

required

Create a new server

authenticated

required

Update server metadata

authenticated

required

Delete a server

MCP execution happens via WebSocket API (not HTTP endpoints). Use superbox pull to configure AI clients.

Authenticated endpoints have higher rate limits (1000 req/hour)

Permission Levels

SuperBox implements resource-level permissions:

Read Permission

All authenticated users can read any server’s information

Write Permission

Only the server owner can update their server’s metadata

Delete Permission

Only the server owner can delete their server

Admin Permission

SuperBox admins can modify or delete any server

Error Responses

Missing Token

{
  "success": false,
  "error": {
 "code": "MISSING_TOKEN",
 "message": "Authentication token is required",
 "details": {
"hint": "Include 'Authorization: Bearer <token>' header"
 }
  }
}

Invalid Token

{
  "success": false,
  "error": {
 "code": "INVALID_TOKEN",
 "message": "Authentication token is invalid or malformed",
 "details": {
"reason": "Invalid signature"
 }
  }
}

Expired Token

{
  "success": false,
  "error": {
 "code": "EXPIRED_TOKEN",
 "message": "Authentication token has expired",
 "details": {
"expiredAt": "2025-12-09T10:30:00Z",
"hint": "Refresh your token and try again"
 }
  }
}

Insufficient Permissions

{
  "success": false,
  "error": {
 "code": "FORBIDDEN",
 "message": "You don't have permission to perform this action",
 "details": {
"required": "owner",
"current": "user"
 }
  }
}

Best Practices

Store Tokens Securely

Use environment variables - Never hardcode tokens in source code - Don’t commit tokens to version control - Use secret management services (AWS Secrets Manager, HashiCorp Vault)

Implement Token Refresh

Check token expiry before requests - Refresh tokens proactively (5 min before expiry) - Handle 401 responses gracefully - Retry failed requests after refresh

Use HTTPS Only

Always use HTTPS for API requests - Never send tokens over unencrypted connections - Validate SSL certificates

Rotate Tokens Regularly

Generate new tokens periodically - Revoke old tokens after rotation - Monitor token usage for anomalies

Monitor for Breaches

Set up alerts for unusual activity - Review access logs regularly - Revoke compromised tokens immediately

SDK Authentication

Using our official SDKs simplifies authentication:

from superbox import SuperBoxClient

# Initialize with token

client = SuperBoxClient(token=os.getenv('SUPERBOX_API_TOKEN'))

# Token refresh is handled automatically

servers = client.servers.list()

import { SuperBoxClient } from '@superbox/sdk';

// Initialize with token
const client = new SuperBoxClient({
  token: process.env.SUPERBOX_API_TOKEN
});

// Token refresh is handled automatically
const servers = await client.servers.list();

package main

import (
 "os"
 "github.com/superbox/sdk-go"
)

func main() {
 // Initialize with token
 client := superbox.NewClient(os.Getenv("SUPERBOX_API_TOKEN"))

 // Token refresh is handled automatically
 servers, err := client.Servers.List()
}

Testing Authentication

Test your authentication setup:

# Test with valid token
curl -X GET "https://api.superbox.ai/api/v1/auth/me" \
  -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

# Expected: 200 OK with user profile

# Test with invalid token
curl -X GET "https://api.superbox.ai/api/v1/auth/me" \
  -H "Authorization: Bearer invalid_token"

# Expected: 401 Unauthorized

# Test without token
curl -X GET "https://api.superbox.ai/api/v1/auth/me"

# Expected: 401 Unauthorized (missing token)

You’re all set! You now know how to authenticate with the SuperBox API.

Next Steps

Create Your First Server

Deploy an MCP server using authenticated endpoints

Error Handling

Learn how to handle authentication errors

Getting Started

Core Concepts

Infrastructure

Backend

Frontend

REST API

Servers API

Auth API

CLI

CLI Commands

Overview

Authentication Method

Getting Your API Token

Google

GitHub

Email

Using Your Token

Environment Variable (Recommended)

Direct Usage

Authentication Flow

Token Validation

Token Structure

Token Payload Example

Token Expiration

Token Lifetime

Automatic Token Refresh

Public vs Authenticated Endpoints

Permission Levels

Error Responses

Missing Token

Invalid Token

Expired Token

Insufficient Permissions

Best Practices

SDK Authentication

Testing Authentication

Next Steps

Create Your First Server

Error Handling

​Overview

Authentication Method

​Getting Your API Token

Google

GitHub

Email

​Using Your Token

​Environment Variable (Recommended)

​Direct Usage

​Authentication Flow

​Token Validation

​Token Structure

​Token Payload Example

​Token Expiration

Token Lifetime

​Automatic Token Refresh

​Public vs Authenticated Endpoints

​Permission Levels

​Error Responses

​Missing Token

​Invalid Token

​Expired Token

​Insufficient Permissions

​Best Practices

​SDK Authentication

​Testing Authentication

​Next Steps

Create Your First Server

Error Handling

Overview

Getting Your API Token

Using Your Token

Environment Variable (Recommended)

Direct Usage

Authentication Flow

Token Validation

Token Structure

Token Payload Example

Token Expiration

Automatic Token Refresh

Public vs Authenticated Endpoints

Permission Levels

Error Responses

Missing Token

Invalid Token

Expired Token

Insufficient Permissions

Best Practices

SDK Authentication

Testing Authentication

Next Steps