API Documentation

Reference for the NikaSites Central Sync API

Overview

The NikaSites Central API handles cross-hive data synchronization for The Hive network. Users with global roles (dev, admin, global-admin) can access their tasks and notes from any connected hive. Data is stored in a central Firestore database and synchronized via this API.

The API runs as a Cloudflare Worker at api.nikasites.com. It accepts Firebase ID tokens from any connected hive for authentication.

Base URL

https://api.nikasites.com

Authentication

All sync endpoints require a Firebase ID token passed as a Bearer token in the Authorization header.

Authorization: Bearer <firebase-id-token>

Auth Flow

1. Client obtains a Firebase ID token from any connected hive's Firebase project
2. Token is sent in the Authorization header
3. Worker decodes the JWT to extract the aud claim (Firebase project ID)
4. Worker looks up the project's API key from its configuration
5. Token is verified via Google Identity Toolkit API
6. User's email is checked against global roles in the central Firestore
7. Only dev, admin, and global-admin roles are authorized

Getting a Token

In your client app, use the Firebase Auth SDK:

const token = await firebase.auth().currentUser.getIdToken();

const response = await fetch('https://api.nikasites.com/sync', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'list',
    type: 'todolists',
    userPath: 'your-sanitized-email'
  })
});

Endpoints

GET /health

Health check endpoint. No authentication required.

// Response
{
  "status": "ok",
  "service": "api.nikasites.com",
  "version": "1.0.0"
}

POST /sync

Authenticated CRUD operations for tasks and notes. Requires a valid Firebase ID token from a global-role user.

Request Body

{
  "action": "list" | "create" | "update",
  "type": "todolists" | "notes",
  "userPath": "sanitized-email",
  "docId": "document-id",     // required for update
  "data": { ... }             // required for create/update
}

The userPath must match the authenticated user's sanitized email. Email sanitization replaces . with _ and _ with __.

List

// Request
{
  "action": "list",
  "type": "todolists",
  "userPath": "user-email-com"
}

// Response
{
  "docs": [
    {
      "id": "abc123",
      "title": "My Tasks",
      "items": [...],
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-02T00:00:00.000Z"
    }
  ]
}

Create

// Request
{
  "action": "create",
  "type": "notes",
  "userPath": "user-email-com",
  "data": {
    "title": "Meeting Notes",
    "content": "Discussed sync architecture..."
  }
}

// Response
{ "id": "auto-generated-document-id" }

Update

// Request
{
  "action": "update",
  "type": "todolists",
  "userPath": "user-email-com",
  "docId": "abc123",
  "data": {
    "title": "Updated Title",
    "items": [...]
  }
}

// Response
{ "ok": true }

Error Codes

Status	Meaning	Example
400	Bad Request	Invalid JSON body, missing required fields
401	Unauthorized	Missing or invalid auth token
403	Forbidden	Not a global user, unknown project, userPath mismatch
404	Not Found	Document not found, unknown endpoint
500	Server Error	Internal error, Firestore failure

All errors return JSON with an error field:

{ "error": "Description of the error" }

CORS

The API accepts requests from registered hive origins and local development ports. Preflight OPTIONS requests are handled automatically. Custom origins can be configured via the ALLOWED_ORIGINS environment variable.