Authentication

Learn how to authenticate with the Fataplus API using session-based auth and API tokens

Overview

The Fataplus API uses session-based authentication with Cloudflare D1 for secure, scalable authentication. The backend is configured with authentication enabled globally across all endpoints.

Authentication Methods

The API supports the following authentication methods:

1. Session-Based Authentication

The primary authentication method using HTTP-only cookies for secure session management.

auth · boolean · default: "true"

Authentication is enabled globally across the API (configured in config.ts:10).

d1.session · boolean · default: "true"

Sessions are stored in Cloudflare D1 database for persistence and scalability (configured in config.ts:5).

How It Works

1. User authenticates via the /auth/login endpoint
2. Server creates a session in D1 database
3. Session ID is returned as an HTTP-only cookie
4. Subsequent requests include the session cookie automatically
5. Server validates session on each request

// Example: Login request
const response = await fetch('https://bknd.fata.plus/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include', // Important: Include cookies
  body: JSON.stringify({
    email: '[e-mail]',
    password: 'your-password'
  })
});

const data = await response.json();
// Session cookie is automatically stored by browser

// Example: Authenticated request
const response = await fetch('https://bknd.fata.plus/api/projects', {
  credentials: 'include' // Include session cookie
});

const projects = await response.json();

2. API Token Authentication

For server-to-server communication or when cookies are not available.

GET /api/projects HTTP/1.1
Host: bknd.fata.plus
Authorization: Bearer YOUR_API_TOKEN

API tokens can be generated through the Admin UI under User Settings.

Role-Based Access Control

The API implements role-based permissions at the collection level:

Available Roles

admin · role

Full access to all collections and operations. Can manage clients, projects, and agricultural data.

client · role

Limited access based on tenant isolation. Can read their own data and manage their projects.

Collection Permissions

Clients Collection

// From config.ts:29-32
permissions: {
  read: ["admin", "client"],
  write: ["admin"]
}

• Read: Both admins and clients can view client records
• Write: Only admins can create/update/delete clients

Projects Collection

// From config.ts:47-50
permissions: {
  read: ["admin", "client"],
  write: ["admin", "client"]
}

• Read: Both admins and clients can view projects
• Write: Both admins and clients can create/update projects

Agricultural Data Collection

// From config.ts:64-67
permissions: {
  read: ["admin", "client"],
  write: ["admin", "client"]
}

• Read: Both admins and clients can view agricultural data
• Write: Both admins and clients can create/update agricultural data

Clients can only access data within their tenant scope. Multi-tenant isolation is enforced at the database level.

CORS Configuration

The API is configured with CORS support for cross-origin requests:

Allowed Origins

// From index.ts:14
cors: {
  origins: [
    "http://localhost:3000",
    "https://fata.plus",
    "https://www.fata.plus",
    "https://fataplus.com",
    "https://www.fataplus.com"
  ],
  credentials: true
}

credentials · boolean · default: "true"

Cookies and authentication headers are allowed in cross-origin requests.

Making Cross-Origin Requests

// Frontend request from https://fata.plus
const response = await fetch('https://bknd.fata.plus/api/projects', {
  method: 'GET',
  credentials: 'include', // Required for cookies
  headers: {
    'Content-Type': 'application/json'
  }
});

The server automatically handles CORS preflight (OPTIONS) requests:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://fata.plus
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true

MCP Endpoint Authentication

The Model Context Protocol endpoint has relaxed CORS for AI tool compatibility:

// From index.ts:54-56
headers: {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization'
}

The MCP endpoint at /api/system/mcp allows all origins (*) to support AI agents and development tools.

Authentication Flow

Standard Web Application Flow

API Token Flow

Security Best Practices

Never expose API tokens in client-side code. Use session-based authentication for web applications and reserve API tokens for server-to-server communication.

Recommendations

1. Use HTTPS: All production requests must use HTTPS
2. Session Cookies: Let the browser handle session cookies automatically
3. CORS Origins: Only allowed origins can make authenticated requests
4. Token Storage: Store API tokens securely in environment variables
5. Password Security: Uses bcryptjs for password hashing (see package.json:14)

Error Responses

401 Unauthorized

Returned when authentication is missing or invalid:

{
  "error": {
    "code": 401,
    "message": "Authentication required"
  }
}

403 Forbidden

Returned when authenticated but lacking required permissions:

{
  "error": {
    "code": 403,
    "message": "Insufficient permissions to access this resource"
  }
}

Testing Authentication

Use the Admin UI to test authentication flows:

https://bknd.fata.plus/admin

The admin interface provides:

• User creation and management
• Role assignment
• API token generation
• Permission testing

Next Steps

API Endpoints

Explore authenticated endpoint usage

Multi-Tenancy

Learn about tenant isolation

MCP Protocol

Integrate AI agents with authentication

Admin UI

Manage users and permissions