Skip to main content

​
Overview

Sorcia uses JWT-based authentication powered by Supabase Auth. All API requests require a valid access token in the Authorization header.
Authentication Flow: Sign up/Login → Email Verification → Access Token → API Requests

​
Authentication Methods

Sorcia supports multiple authentication methods:

Email & Password

Traditional email/password authentication

Magic Link

Passwordless login via email

OAuth

Google, GitHub, Microsoft (Enterprise)

API Keys

Server-to-server authentication

​
Sign Up

Create a new user account and organization. 
curl -X POST https://api.sorcia.ai/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "SecurePass123!",
    "organizationName": "Acme Inc"
  }'

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
Password (minimum 6 characters)
​
organizationName
string
required
Name of the organization to create

​
Response

{
  "success": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@company.com"
  },
  "message": "Please check your email to verify your account"
}
Email Verification Required: Users must verify their email before they can log in.

​
Login

Authenticate with email and password to receive an access token. 
curl -X POST https://api.sorcia.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "SecurePass123!"
  }'

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "v1.MR5twgYWhT3y8pE4F-foo4o2M4g...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@company.com",
    "organization_id": "660e8400-e29b-41d4-a716-446655440001"
  }
}
​
access_token
string
JWT access token (valid for 1 hour)
​
refresh_token
string
Refresh token for obtaining new access tokens
​
expires_in
number
Token expiration time in seconds
Request a passwordless login link sent via email. 
curl -X POST https://api.sorcia.ai/api/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com"
  }'

​
Response

{
  "success": true,
  "message": "Check your email for a login link"
}
Magic links expire after 1 hour and can only be used once.

​
Refresh Token

Exchange a refresh token for a new access token. 
curl -X POST https://api.sorcia.ai/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "v1.MR5twgYWhT3y8pE4F-foo4o2M4g..."
  }'

​
Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "v1.NewRefreshTokenHere...",
  "expires_in": 3600,
  "token_type": "bearer"
}

​
Making Authenticated Requests

Include the access token in the Authorization header for all API requests: 
curl https://api.sorcia.ai/api/ai/query \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is our vacation policy?"
  }'

​
API Keys (Server-to-Server)

For server-to-server integrations, use API keys instead of user tokens.

​
Generate API Key

  1. Navigate to Settings → API Keys
  2. Click Create API Key
  3. Name your key (e.g., “Production Server”)
  4. Copy the key immediately (it won’t be shown again)
Security: API keys have full access to your organization. Store them securely and never commit them to version control.

​
Using API Keys

Include the API key in the X-API-Key header: 
curl https://api.sorcia.ai/api/ai/query \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"question": "What is our vacation policy?"}'

​
Rotate API Keys

Regularly rotate API keys for security:
  1. Generate a new API key
  2. Update your applications to use the new key
  3. Delete the old key once migration is complete

​
Error Responses

​
Unauthorized (401)

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}
Solutions:
  • Verify token is included in header
  • Check token hasn’t expired
  • Refresh token if needed

​
Forbidden (403)

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
Solutions:
  • Verify user has required role
  • Check organization membership
  • Contact admin for access

​
Rate Limited (429)

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retry_after": 60
}
Solutions:
  • Implement exponential backoff
  • Reduce request frequency
  • Upgrade plan for higher limits

​
Rate Limits

API rate limits vary by plan:
PlanRequests/MinuteBurst Limit
Free1020
Pro100200
Enterprise10002000
Monitor your rate limit usage via the X-RateLimit-* response headers.

​
Best Practices

  • Never store tokens in localStorage (XSS vulnerable)
  • Use httpOnly cookies for web apps
  • Use secure storage (Keychain/Keystore) for mobile apps
  • Encrypt tokens at rest in databases
  • Implement automatic token refresh
  • Handle 401 errors gracefully
  • Show re-login prompt when refresh fails
  • Never send tokens over HTTP
  • Enable HSTS in production
  • Pin certificates for mobile apps
  • Clear tokens on logout
  • Revoke refresh tokens server-side
  • Clear all session data

​
Next Steps

Query API

Learn how to search your knowledge base

Organizations API

Manage organizations and members