Skip to main content

​
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

1

Create an Account

Sign up at SuperBox using one of our supported providers:

Google

Sign in with Google

GitHub

Sign in with GitHub

Email

Email/Password
2

Navigate to Settings

Go to your Profile Settings page.
3

Generate API Token

Click “Generate API Token” to create a new authentication token.
This token will only be shown once. Store it securely!
4

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

Store your token in an environment variable: 
export SUPERBOX_API_TOKEN="your_firebase_jwt_token_here"
Then reference it in your code: 
cURL
curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Authorization: Bearer $SUPERBOX_API_TOKEN"

​
Direct Usage

For testing or development, you can use the token directly: 
cURL
curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5..."

​
Authentication Flow

​
Token Validation

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

Extract Token

API extracts the Bearer token from the Authorization header
2

Verify Signature

Token signature is verified using Firebase public keys
3

Check Expiration

Token expiration time is checked
4

Extract Claims

User ID and other claims are extracted from the token
5

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"
  }
}
​
user_id
string
Unique user identifier
​
email
string
User’s email address
​
exp
integer
Token expiration timestamp (Unix time)
​
iat
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: 
JavaScript
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}`
}
});
}

​
Public vs Authenticated Endpoints

These endpoints don’t require authentication:
​
GET /servers
public
List all servers (read-only)
​
GET /servers/:name
public
Get server details (read-only)
Public endpoints have stricter rate limits (100 req/hour)

​
Permission Levels

SuperBox implements resource-level permissions:
All authenticated users can read any server’s information
Only the server owner can update their server’s metadata
Only the server owner can delete their server
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

  • 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)
  • Check token expiry before requests - Refresh tokens proactively (5 min before expiry) - Handle 401 responses gracefully - Retry failed requests after refresh
  • Always use HTTPS for API requests - Never send tokens over unencrypted connections - Validate SSL certificates
  • Generate new tokens periodically - Revoke old tokens after rotation - Monitor token usage for anomalies
  • Set up alerts for unusual activity - Review access logs regularly - Revoke compromised tokens immediately

​
SDK Authentication

Using our official SDKs simplifies authentication: 
Python SDK
from superbox import SuperBoxClient

# Initialize with token

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

# Token refresh is handled automatically

servers = client.servers.list()

​
Testing Authentication

Test your authentication setup: 
# Test with valid token
curl -X GET "https://api.superbox.ai/api/v1/user/profile" \
  -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/user/profile" \
  -H "Authorization: Bearer invalid_token"

# Expected: 401 Unauthorized

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

# 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