Authentication

Cortif.AI uses Better Auth for secure authentication. All API endpoints require authentication unless otherwise specified.

Authentication Methods

1. Session-Based Authentication (Recommended)

For web applications, use session-based authentication with HTTP-only cookies.

Create a new user account with organization.

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

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePassword123",
  "organizationName": "Acme Corp",
  "role": "admin"
}

{
  "success": true,
  "message": "Account created successfully",
  "user": {
    "id": "user_123",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "admin"
  }
}

curl -X POST https://api.cortif.ai/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securePassword123",
    "organizationName": "Acme Corp",
    "role": "admin"
  }'

Authenticate with existing credentials.

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

{
  "email": "john@example.com",
  "password": "securePassword123"
}

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "user_123",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "admin"
  }
}

curl -X POST https://api.cortif.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "securePassword123"
  }' \
  -c cookies.txt

Get Session

Retrieve current user session information.

GET /api/auth/get-session
Cookie: session-token=your_session_token

{
  "success": true,
  "user": {
    "id": "user_123",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "admin",
    "organizationId": "org_456"
  },
  "session": {
    "id": "session_789",
    "expiresAt": "2024-01-15T10:30:00Z"
  }
}

curl -X GET https://api.cortif.ai/api/auth/get-session \
  -b cookies.txt

Sign Out

Terminate the current session.

POST /api/auth/logout
Cookie: session-token=your_session_token

{
  "success": true,
  "message": "Logged out successfully"
}

curl -X POST https://api.cortif.ai/api/auth/logout \
  -b cookies.txt

2. Email Verification

Cortif.AI supports email verification for enhanced security.

Send OTP

Send a one-time password to the user's email.

POST /api/send-otp
Content-Type: application/json

{
  "email": "john@example.com"
}

{
  "success": true,
  "message": "OTP sent successfully"
}

Verify OTP

Verify the one-time password.

POST /api/verify-otp
Content-Type: application/json

{
  "email": "john@example.com",
  "otp": "123456"
}

{
  "success": true,
  "message": "OTP verified successfully"
}

Error Handling

Authentication errors follow standard HTTP status codes:

Status Code	Description
`401`	Unauthorized - Invalid credentials or session expired
`403`	Forbidden - Insufficient permissions
`422`	Validation Error - Invalid input data
`429`	Rate Limited - Too many requests

Error Response Format

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Security Best Practices

Security Guidelines

Always use HTTPS in production
Store session tokens securely (HTTP-only cookies recommended)
Implement proper session timeout
Use strong passwords (minimum 8 characters)
Enable email verification for sensitive operations

Rate Limiting

Authentication endpoints are rate-limited to prevent abuse:

Login attempts: 5 per minute per IP
OTP requests: 3 per minute per email
Session checks: 100 per minute per user

SDK Examples

JavaScript/TypeScript

import { CortifClient } from "@cortif/sdk";

const client = new CortifClient({
  baseURL: "https://api.cortif.ai",
  credentials: "include", // For session cookies
});

// Sign up
const user = await client.auth.signUp({
  name: "John Doe",
  email: "john@example.com",
  password: "securePassword123",
  organizationName: "Acme Corp",
});

// Sign in
await client.auth.signIn({
  email: "john@example.com",
  password: "securePassword123",
});

// Get current session
const session = await client.auth.getSession();

Python

import requests

class CortifClient:
    def __init__(self, base_url="https://api.cortif.ai"):
        self.base_url = base_url
        self.session = requests.Session()

    def sign_up(self, name, email, password, organization_name=None):
        response = self.session.post(f"{self.base_url}/api/auth/signup", json={
            "name": name,
            "email": email,
            "password": password,
            "organizationName": organization_name
        })
        return response.json()

    def sign_in(self, email, password):
        response = self.session.post(f"{self.base_url}/api/auth/login", json={
            "email": email,
            "password": password
        })
        return response.json()

# Usage
client = CortifClient()
client.sign_in("john@example.com", "securePassword123")

Next Steps

Once authenticated, you can:

Authentication

Security Guidelines

On this page