Authentication

Sophosic Platform uses Supabase Auth with Bearer token authentication for API access.

Getting Your API Key

Log in to Sophosic Dashboard
Navigate to Settings → API Keys
Click Generate New Key
Copy and store securely (never commit to version control)

Authentication Methods

Bearer Token (Recommended)

Include your API key in the Authorization header:


curl https://api.sophosic.ai/api/chat/v5 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Supabase Session Token

For frontend applications, use Supabase session tokens:


import { createClient } from '@supabase/supabase-js';
 
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
);
 
const {
  data: { session },
} = await supabase.auth.getSession();
 
const response = await fetch('https://api.sophosic.ai/api/chat/v5', {
  headers: {
    Authorization: `Bearer ${session.access_token}`,
  },
});

Security Best Practices

API Key Storage

✅ DO:

Store in environment variables
Use secret management services (Vault, AWS Secrets Manager)
Rotate keys regularly
Use different keys for development/production

❌ DON’T:

Hardcode in source code
Commit to version control
Share via insecure channels
Use same key across environments

Example: Environment Variables


# .env.local (never commit this file)
SOPHOSIC_API_KEY=sk_live_abc123xyz789


// Using in code
const apiKey = process.env.SOPHOSIC_API_KEY;

Row-Level Security (RLS)

All database access is protected by PostgreSQL RLS policies ensuring:

Users can only access their own data
Multi-tenant isolation enforced at database level
Automatic filtering by user_id
Cascading deletes for account cleanup

Rate Limits

Authentication includes rate limiting per API key:

Tier	Requests/Hour	Burst
Free	100	20
Pro	1,000	100
Enterprise	Custom	Custom

Rate Limit Headers

Response headers indicate your current limits:


X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640995200

Error Responses

401 Unauthorized


{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "statusCode": 401
}

Common causes:

Missing Authorization header
Invalid API key format
Expired or revoked key

403 Forbidden


{
  "error": "Forbidden",
  "message": "Insufficient permissions",
  "statusCode": 403
}

Common causes:

Attempting to access another user’s resources
Feature not available in your tier
Account suspended

429 Too Many Requests


{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "statusCode": 429,
  "retryAfter": 3600
}

Solution: Wait for rate limit reset or upgrade to higher tier.

OAuth Integration

For third-party integrations, Sophosic supports OAuth 2.0:


# Authorization endpoint
GET https://sophosic.ai/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read_profile%20read_data
 
# Token exchange
POST https://sophosic.ai/oauth/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code&
code=AUTH_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

See OAuth Guide for complete implementation.

Testing Authentication

Verify your API key works:


curl https://api.sophosic.ai/api/auth/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response:


{
  "id": "user_abc123",
  "email": "developer@example.com",
  "tier": "pro",
  "created_at": "2025-01-01T00:00:00Z"
}

Next Steps

Quickstart Guide - Make your first API request
Rate Limits - Understand usage limits
Error Handling - Handle authentication errors