API Authentication

The Torvus API uses Supabase authentication with JWT bearer tokens for secure API access.

Authentication Methods

1. JWT Bearer Tokens (Recommended)

The primary authentication method for the Torvus API uses JSON Web Tokens (JWT) obtained through Supabase Auth.

Authentication Flow:

1. User authenticates via Supabase (magic link, password, or OAuth)
2. Supabase returns an access token (JWT)
3. Include the JWT in the Authorization header for API requests
4. Tokens are validated server-side on each request

Example Request:

curl -X GET https://platform.torvussecurity.com/api/vaults \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

2. API Keys (Service Accounts)

For server-to-server integrations and automation, use API keys.

Coming Soon: API key management is currently in development.

3. OAuth 2.0 (Third-Party Integrations)

OAuth 2.0 support for third-party applications is planned for a future release.

Getting Your Access Token

Web Application

If you're building a web application:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
)

// Sign in with magic link
const { data, error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com'
})

// Get access token
const { data: { session } } = await supabase.auth.getSession()
const accessToken = session?.access_token

Mobile/Desktop Application

Use the Supabase client library for your platform:

React Native:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(url, anonKey)
const { data: { session } } = await supabase.auth.getSession()

Flutter:

import 'package:supabase_flutter/supabase_flutter.dart';

final session = Supabase.instance.client.auth.currentSession;
final accessToken = session?.accessToken;

Making Authenticated Requests

Header Format

Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Example Requests

JavaScript/TypeScript:

const response = await fetch('https://platform.torvussecurity.com/api/vaults', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
})

Python:

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://platform.torvussecurity.com/api/vaults',
    headers=headers
)

cURL:

curl -X GET https://platform.torvussecurity.com/api/vaults \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type": application/json"

Token Lifecycle

Token Expiration

• Access tokens expire after 1 hour
• Refresh tokens expire after 7 days (configurable)

Refreshing Tokens

Use the refresh token to obtain a new access token:

const { data, error } = await supabase.auth.refreshSession()
const newAccessToken = data.session?.access_token

Automatic Refresh

The Supabase client automatically refreshes tokens:

// Enable automatic refresh (enabled by default)
const supabase = createClient(url, anonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true
  }
})

Error Handling

Authentication Errors

Status Code	Error	Description
401	Unauthorized	Missing or invalid JWT token
403	Forbidden	Valid token but insufficient permissions
419	Token Expired	JWT token has expired, refresh required

Error Response Format

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token",
  "statusCode": 401
}

Handling Token Expiration

async function makeAuthenticatedRequest(url: string) {
  try {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    })

    if (response.status === 419) {
      // Token expired, refresh and retry
      const { data } = await supabase.auth.refreshSession()
      accessToken = data.session?.access_token

      // Retry request with new token
      return fetch(url, {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      })
    }

    return response
  } catch (error) {
    console.error('Authentication error:', error)
    throw error
  }
}

Security Best Practices

Token Storage

Web Applications:

• Store tokens in memory when possible
• Use HttpOnly cookies for enhanced security
• Never store tokens in localStorage for sensitive applications

Mobile Applications:

• Use secure storage (Keychain on iOS, Keystore on Android)
• Enable biometric protection for token access

Token Transmission

• Always use HTTPS for API requests
• Never include tokens in URL parameters
• Use POST requests for sensitive operations

Token Validation

Server-side token validation includes:

• Signature verification
• Expiration check
• Issuer validation
• Audience validation

Rate Limiting

API requests are rate limited based on authentication:

Authentication Type	Rate Limit
Authenticated users	1000 requests/hour
Unauthenticated	100 requests/hour
API keys (future)	Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Testing Authentication

Postman/Insomnia

1. Get your access token from Supabase
2. Add to Authorization header:
   • Type: Bearer Token
   • Token: <your-access-token>

cURL Test

# Test authentication
curl -X GET https://platform.torvussecurity.com/api/me \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -v

Expected response (200 OK):

{
  "id": "uuid",
  "email": "user@example.com",
  "created_at": "2024-01-01T00:00:00Z"
}

Next Steps

• Security Overview

Coming Soon:

• API Reference
• Webhooks
• Rate Limiting