Getting Started

Authentication

CognitionDesk supports three authentication mechanisms depending on your use case: Firebase ID Tokens for frontend apps, API Keys for server integrations, and HMAC signatures for incoming webhooks.

Methods Overview

Method	Header	Best For
Firebase ID Token	`Authorization: Bearer <token>`	Frontend (browser) apps
API Key	`x-api-key: sk_live_...`	Server-to-server integrations
HMAC-SHA256	`x-hub-signature-256 / x-webhook-secret`	Inbound webhooks (Meta, Stripe, internal)

1. Firebase ID Token

The primary authentication method for all frontend applications using Firebase Auth. The backend verifies tokens via firebase-admin on every request.

auth-firebase.js

JavaScript

// 1. Get the token on the frontend
import { getAuth } from 'firebase/auth';

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

// 2. Include it in every request
const response = await fetch('https://api.cognitiondesk.com/knowledge-base/entries', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

Token expiry: Firebase tokens expire after 1 hour. Use getIdToken(true) to force a refresh, or rely on the Firebase SDK's automatic refresh.

2. API Key

For server-to-server integrations. Keys are validated against Firestore and cached in memory for 10 minutes to reduce database reads.

Generate API Key

HTTP

POST /apikeys/generate-api-key
Authorization: Bearer <firebase-id-token>

// Response
{
  "apiKey": "sk_live_...",
  "createdAt": "2026-01-15T10:30:00Z"
}

auth-apikey.js

JavaScript

// Server-side: use x-api-key header
const response = await fetch('https://api.cognitiondesk.com/chat-apiKeyAuth/chat', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.COGNITIONDESK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Hello', assistantId: 'asst_...' }),
});

3. Webhook Signatures (HMAC)

All inbound webhooks are verified with HMAC-SHA256 signatures. Each provider uses a slightly different header name:

Provider	Signature Header
Meta / WhatsApp	`x-hub-signature-256`
Stripe	`stripe-signature`
LemonSqueezy	`x-signature`
Internal (BillingService)	`x-webhook-secret`

verify-webhook.js

JavaScript

// Verify Meta/WhatsApp webhook signature
import crypto from 'crypto';

function verifyMetaSignature(payload, signature, appSecret) {
  const expected = crypto
    .createHmac('sha256', appSecret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

// In your Express route:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-hub-signature-256'];
  const isValid = verifyMetaSignature(
    JSON.stringify(req.body),
    sig,
    process.env.META_APP_SECRET
  );

  if (!isValid) return res.status(401).json({ error: 'Invalid signature' });
  // process webhook...
});

4. RBAC — Role-Based Access Control

Beyond authentication, CognitionDesk enforces role-based permissions on organizations and projects. The backend middleware checks membership before allowing write operations.

TypeScript

// RBAC roles in CognitionDesk
type Role = 'owner' | 'admin' | 'member' | 'viewer';

// Permissions by role:
// owner  → full CRUD + billing + member management
// admin  → full CRUD + member management
// member → read + create resources
// viewer → read-only

// The backend middleware checks:
// requireOrganizationPermission('admin')
// requireProjectPermission('member')