Authentication API

The Authentication API handles user registration, login, and session management for the Pomelo platform.

Base URLs

• POST /api/auth/signup - User registration
• GET /api/auth/callback - OAuth callback handler
• Session-based authentication for web interface
• API key authentication for programmatic access

Authentication Methods

The API supports two authentication methods:

1. Session-based authentication - For web interface and dashboard
2. API key authentication - For programmatic API access

User Registration

Register a new user account.

Request

POST /api/auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password",
  "name": "John Doe"
}

Parameters

Response

{
  "success": true,
  "message": "Account created successfully",
  "user": {
    "id": "user_123456789",
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-01-16T15:30:00Z"
  }
}

OAuth Callback

Handles OAuth authentication callbacks (Google, GitHub, etc.).

Request

GET /api/auth/callback?code=AUTH_CODE&state=STATE_TOKEN

This endpoint is typically called by OAuth providers and not directly by users.

Parameters

Response

Redirects to the dashboard or login page based on authentication result.

Session Authentication

For web interface users, authentication is handled via secure HTTP-only cookies.

Login Process

1. User visits /login page
2. Enters credentials or uses OAuth
3. Server creates secure session
4. Session cookie is set
5. User can access protected routes

Session Management

Sessions are automatically managed:

• Duration: 7 days (configurable)
• Security: HTTP-only, Secure, SameSite cookies
• Renewal: Automatic on active use
• Logout: Clear session and cookies

API Key Authentication

For programmatic access, use API keys in the Authorization header.

Using API Keys

Authorization: Bearer YOUR_API_KEY

API Key Format

API keys follow this format:

ak-proj-1234567890abcdef1234567890abcdef

• ak - Prefix indicating Pomelo key
• proj - Project or environment identifier
• 1234... - Unique key identifier

Security Headers

API requests should include these headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
User-Agent: YourApp/1.0

Protected Routes

Dashboard Routes (Session Auth)

• /dashboard/* - All dashboard pages
• /settings/* - User settings
• /api/keys - API key management
• /api/billing/credits - Credit balance

API Routes (API Key Auth)

• /api/v1/task - AI task processing
• /api/v1/models - Model information
• /api/billing/* - Billing operations (some endpoints)

Error Responses

Invalid Credentials

{
  "error": {
    "message": "Invalid email or password",
    "type": "authentication_error",
    "code": "invalid_credentials"
  }
}

Account Already Exists

{
  "error": {
    "message": "Account with this email already exists",
    "type": "registration_error", 
    "code": "account_exists"
  }
}

Invalid API Key

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Session Expired

{
  "error": {
    "message": "Session expired, please login again",
    "type": "authentication_error",
    "code": "session_expired"
  }
}

Rate Limited

{
  "error": {
    "message": "Too many authentication attempts",
    "type": "rate_limit_error",
    "code": "auth_rate_limit"
  }
}

Usage Examples

Registration (JavaScript)

const response = await fetch('/api/auth/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'secure_password',
    name: 'John Doe'
  })
});

const data = await response.json();
if (data.success) {
  console.log('Account created:', data.user);
} else {
  console.log('Error:', data.error);
}

API Key Usage (JavaScript)

const apiKey = 'ak-proj-1234567890abcdef1234567890abcdef';

const response = await fetch('/api/v1/task', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

const data = await response.json();

Session Check (JavaScript)

// Check if user is authenticated
const response = await fetch('/api/auth/me', {
  credentials: 'include' // Include session cookies
});

if (response.ok) {
  const user = await response.json();
  console.log('Authenticated user:', user);
} else {
  console.log('Not authenticated, redirect to login');
  window.location.href = '/login';
}

Using cURL

Register Account

curl -X POST https://your-domain.com/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password",
    "name": "John Doe"
  }'

API Request with Key

curl -X POST https://your-domain.com/api/v1/task \
  -H "Authorization: Bearer ak-proj-1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Security Best Practices

For API Keys

1. Store securely: Never expose API keys in client-side code
2. Use environment variables: Store keys in environment variables
3. Rotate regularly: Generate new keys and revoke old ones periodically
4. Monitor usage: Check API key usage patterns for anomalies
5. Restrict permissions: Use separate keys for different environments

For Sessions

1. Use HTTPS: Always use secure connections in production
2. Secure cookies: HTTP-only, Secure, and SameSite attributes
3. Session timeout: Implement appropriate session timeouts
4. CSRF protection: Use CSRF tokens for state-changing operations
5. Account lockout: Implement lockout after multiple failed attempts

Password Requirements

• Minimum 8 characters
• Mix of uppercase and lowercase letters
• At least one number
• At least one special character
• Not commonly used passwords

OAuth Providers

Supported OAuth providers:

• Google - Sign in with Google account
• GitHub - Sign in with GitHub account
• Microsoft - Sign in with Microsoft account (coming soon)

OAuth Flow

1. User clicks "Sign in with [Provider]"
2. Redirect to provider's authorization page
3. User grants permissions
4. Provider redirects back with authorization code
5. Server exchanges code for access token
6. User profile is created/updated
7. User is signed in

Rate Limits

Authentication endpoints have specific rate limits:

• Registration: 5 attempts per hour per IP
• Login: 10 attempts per hour per IP
• Password reset: 3 attempts per hour per email
• API key usage: Based on subscription plan

Account Management

Password Reset

Password reset is handled through email:

1. User requests password reset
2. Email with reset link is sent
3. User clicks link and enters new password
4. Password is updated and user can login

Account Deletion

Users can delete their accounts:

1. All API keys are revoked
2. User data is anonymized or deleted
3. Subscription is cancelled
4. Account is permanently deleted

Email Verification

New accounts require email verification:

1. Verification email is sent during registration
2. User clicks verification link
3. Account is activated
4. User can access all features

Troubleshooting

Common Issues

1. API key not working: Check key format and permissions
2. Session expired: Clear cookies and login again
3. Registration fails: Check email format and password requirements
4. OAuth errors: Verify redirect URLs and provider settings

Debug Information

For development, authentication errors include debug information:

{
  "error": {
    "message": "Authentication failed",
    "type": "authentication_error",
    "code": "invalid_credentials",
    "debug": {
      "timestamp": "2024-01-16T15:30:00Z",
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    }
  }
}

Note: Debug information is only included in development environments.