Core Platform API

Authentication, user management, notifications, chat, billing, entity registry, and platform configuration.

~100 endpoints

Authentication

Login, token management, password reset, and profile endpoints.

POST /api/v1/auth/login

Authenticate with email, password, and tenant slug. Returns access and refresh tokens.

Auth: None (public)

Request Body
json 
{
  "email": "user@company.com",
  "password": "your-password",
  "tenantSlug": "your-tenant"
}
Response
json 
{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "user": { "id": "uuid", "email": "..." }
  }
}
POST /api/v1/auth/refresh

Refresh access token using a valid refresh token.

Auth: None (public)

Request Body
json 
{
  "refreshToken": "eyJ..."
}
POST /api/v1/auth/logout

Invalidate the current refresh token.

Auth: Bearer token

POST /api/v1/auth/logout-all

Invalidate all refresh tokens for the current user (logout all devices).

Auth: Bearer token

POST /api/v1/auth/password/forgot

Request a password reset email. Rate limited to 5 per hour.

Auth: None (public)

Request Body
json 
{
  "email": "user@company.com",
  "tenantSlug": "your-tenant"
}
POST /api/v1/auth/password/reset

Reset password using a token from the reset email.

Auth: None (public)

Request Body
json 
{
  "token": "reset-token",
  "password": "new-password"
}
POST /api/v1/auth/password/change

Change password for the authenticated user.

Auth: Bearer token

Request Body
json 
{
  "currentPassword": "old-password",
  "newPassword": "new-password"
}
GET /api/v1/auth/verify-email/:token

Verify email address using the token from verification email.

Auth: None (public)

GET /api/v1/auth/me

Get current authenticated user details.

Auth: Bearer token

GET /api/v1/auth/me/preferences

Get current user's preferences (UI settings, notification settings).

Auth: Bearer token

GET /api/v1/auth/me/profile

Get extended user profile including phone, avatar, timezone, and locale.

Auth: Bearer token

PUT /api/v1/auth/me/profile

Update user profile fields (phone, avatar, timezone, locale).

Auth: Bearer token

Request Body
json 
{
  "phone": "+1234567890",
  "timezone": "America/New_York",
  "locale": "en-US"
}
PUT /api/v1/auth/me/preferences

Update user preferences.

Auth: Bearer token

Users

Manage tenant users — create, invite, activate, deactivate.

POST /api/v1/users

Create a new user and send invitation email.

Auth: Bearer token · tenant_admin or manager

Request Body
json 
{
  "email": "newuser@company.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "role": "user",
  "profileId": 1
}
GET /api/v1/users

List users in the current tenant with pagination and filtering.

Auth: Bearer token

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
search string Search by name or email
status string Filter by status (active/inactive)
GET /api/v1/users/profiles

List available permission profiles for user assignment.

Auth: Bearer token

GET /api/v1/users/me

Get current authenticated user.

Auth: Bearer token

GET /api/v1/users/:id

Get a specific user by ID.

Auth: Bearer token

PUT /api/v1/users/:id

Update user details (name, role, profile, status).

Auth: Bearer token · tenant_admin or manager

DELETE /api/v1/users/:id

Deactivate a user (soft delete).

Auth: Bearer token · tenant_admin

POST /api/v1/users/:id/activate

Reactivate a deactivated user.

Auth: Bearer token · tenant_admin

POST /api/v1/users/:id/resend-invitation

Resend the invitation email to a pending user.

Auth: Bearer token · tenant_admin

POST /api/v1/users/accept-invitation

Accept an invitation and set password. Public endpoint.

Auth: None (public)

Request Body
json 
{
  "token": "invitation-token",
  "password": "your-password"
}
DELETE /api/v1/users/:id/permanent

Permanently delete a user. Irreversible.

Auth: Bearer token · tenant_admin

Tenants

Tenant registration and lookup.

POST /api/v1/tenants/register

Register a new tenant with an admin user.

Auth: None (public)

Request Body
json 
{
  "companyName": "Acme Corp",
  "slug": "acme-corp",
  "adminEmail": "admin@acme.com",
  "adminPassword": "secure-password",
  "adminFirstName": "John",
  "adminLastName": "Doe"
}
GET /api/v1/tenants/me

Get current tenant information.

Auth: Bearer token

GET /api/v1/tenants/by-slug/:slug

Get tenant by slug (for login page customization).

Auth: None (public)

GET /api/v1/tenants/check-slug/:slug

Check if a tenant slug is available.

Auth: None (public)

Permission Profiles

Create and manage custom permission profiles.

GET /api/v1/profiles

List all permission profiles with user counts.

Auth: Bearer token

GET /api/v1/profiles/permissions

List all available permissions in the system.

Auth: Bearer token

GET /api/v1/profiles/:id

Get profile detail with assigned permission IDs.

Auth: Bearer token

POST /api/v1/profiles

Create a new custom permission profile.

Auth: Bearer token · tenant_admin

Request Body
json 
{
  "name": "Sales Manager",
  "description": "Full sales access with approval",
  "permissions": [1, 2, 3, 4]
}
PUT /api/v1/profiles/:id

Update a custom profile's name, description, or permissions.

Auth: Bearer token · tenant_admin

DELETE /api/v1/profiles/:id

Deactivate a permission profile (soft delete).

Auth: Bearer token · tenant_admin

POST /api/v1/profiles/:id/activate

Reactivate a deactivated profile.

Auth: Bearer token · tenant_admin

Permissions

Query current user permissions.

GET /api/v1/permissions/me

Get the current user's permissions and role.

Auth: Bearer token

Organization Settings

Tenant-level configuration settings.

GET /api/v1/org-settings

List all organization settings as a key-value map.

Auth: Bearer token

GET /api/v1/org-settings/by-category/:category

Get settings filtered by category.

Auth: Bearer token

GET /api/v1/org-settings/:key

Get a specific setting by key.

Auth: Bearer token

PUT /api/v1/org-settings/:key

Update a setting value.

Auth: Bearer token · tenant_admin

Email Settings

SMTP, sender, tracking, compliance, footer, and deliverability configuration.

GET /api/v1/settings/email/smtp

Get SMTP configuration.

Auth: Bearer token · tenant_admin

PUT /api/v1/settings/email/smtp

Save SMTP configuration.

Auth: Bearer token · tenant_admin

POST /api/v1/settings/email/smtp/test

Test SMTP connection with current configuration.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/sender

Get sender defaults (from name, reply-to).

Auth: Bearer token

PUT /api/v1/settings/email/sender

Update sender defaults.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/tracking

Get email tracking configuration (open/click tracking).

Auth: Bearer token

PUT /api/v1/settings/email/tracking

Update email tracking configuration.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/compliance

Get email compliance configuration (CAN-SPAM, GDPR).

Auth: Bearer token

PUT /api/v1/settings/email/compliance

Update compliance configuration.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/footer

Get email footer configuration.

Auth: Bearer token

PUT /api/v1/settings/email/footer

Update email footer configuration.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/deliverability

Get deliverability configuration (SPF, DKIM guidance).

Auth: Bearer token

PUT /api/v1/settings/email/deliverability

Update deliverability configuration.

Auth: Bearer token · tenant_admin

GET /api/v1/settings/email/status

Get overall email configuration status and readiness.

Auth: Bearer token

Notifications

In-app notification management.

GET /api/v1/notifications

List notifications for the current user with pagination.

Auth: Bearer token

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
unread boolean Filter unread only
GET /api/v1/notifications/unread-count

Get the count of unread notifications.

Auth: Bearer token

PATCH /api/v1/notifications/:id/read

Mark a single notification as read.

Auth: Bearer token

POST /api/v1/notifications/mark-all-read

Mark all notifications as read.

Auth: Bearer token

DELETE /api/v1/notifications/:id

Dismiss a notification.

Auth: Bearer token

Notification Preferences

Per-user notification channel and Do Not Disturb settings.

GET /api/v1/notifications/preferences/catalog

Get all notification events grouped by module with override flags.

Auth: Bearer token

GET /api/v1/notifications/preferences

Get current user's preferences merged with system defaults.

Auth: Bearer token

POST /api/v1/notifications/preferences

Set a notification preference (eventKey, channel, enabled) with upsert.

Auth: Bearer token

Request Body
json 
{
  "eventKey": "sales.lead_assigned",
  "channel": "email",
  "enabled": false
}
GET /api/v1/notifications/preferences/dnd

Get Do Not Disturb settings.

Auth: Bearer token

PUT /api/v1/notifications/preferences/dnd

Update Do Not Disturb schedule.

Auth: Bearer token

Request Body
json 
{
  "enabled": true,
  "startTime": "22:00",
  "endTime": "08:00",
  "timezone": "America/New_York"
}

Notification Templates

Customize notification email and in-app templates.

GET /api/v1/notifications/templates

List all notification templates grouped by module.

Auth: Bearer token

GET /api/v1/notifications/templates/:id

Get template detail with subject, body, and variables.

Auth: Bearer token

POST /api/v1/notifications/templates/:id/customize

Save a custom override for a notification template.

Auth: Bearer token · tenant_admin

POST /api/v1/notifications/templates/:id/preview

Preview a template rendered with sample data.

Auth: Bearer token

DELETE /api/v1/notifications/templates/:id/override

Reset a customized template back to system default.

Auth: Bearer token · tenant_admin

Notification Analytics

Delivery metrics, digest settings, and analytics.

GET /api/v1/notifications/analytics

Get delivery overview with metrics, per-event stats, channel breakdown, and daily trend.

Auth: Bearer token

GET /api/v1/notifications/analytics/digest

Get digest delivery statistics.

Auth: Bearer token

GET /api/v1/notifications/analytics/digest/settings

Get current user's digest settings (frequency, time).

Auth: Bearer token

PUT /api/v1/notifications/analytics/digest/settings

Update digest settings.

Auth: Bearer token

Chat

Real-time messaging — direct messages and group channels.

GET /api/v1/chat/users

List all active tenant users for the chat user picker.

Auth: Bearer token

GET /api/v1/chat/channels

Get all chat channels for the current user.

Auth: Bearer token

POST /api/v1/chat/channels/direct

Start or resume a direct message channel with another user.

Auth: Bearer token

Request Body
json 
{
  "userId": 5
}
POST /api/v1/chat/channels/group

Create a group channel with multiple members.

Auth: Bearer token

Request Body
json 
{
  "name": "Project Alpha",
  "memberIds": [2, 5, 8]
}
GET /api/v1/chat/channels/:id/messages

Get messages in a channel with cursor-based pagination.

Auth: Bearer token

Query Parameters
Parameter Type Description
cursor string Cursor for pagination
limit number Messages per page (default 50)
POST /api/v1/chat/channels/:id/messages

Send a message in a channel.

Auth: Bearer token

Request Body
json 
{
  "content": "Hello team!"
}
POST /api/v1/chat/channels/:id/read

Mark a channel as read up to the latest message.

Auth: Bearer token

GET /api/v1/chat/unread-count

Get total unread message count across all channels.

Auth: Bearer token

Billing

Subscription management and checkout.

GET /api/v1/billing/status

Get billing status for the current tenant (plan, seats, trial info).

Auth: Bearer token

POST /api/v1/billing/checkout

Create a Stripe checkout session for subscription.

Auth: Bearer token · tenant_admin

Request Body
json 
{
  "planId": "pro",
  "interval": "monthly"
}
POST /api/v1/billing/portal

Create a Stripe customer portal session for managing subscription.

Auth: Bearer token · tenant_admin

POST /api/v1/billing/cancel

Cancel the current subscription.

Auth: Bearer token · tenant_admin

Entity Registry

Unified entity management across modules — canonical records, linking, merging.

GET /api/v1/entity-registry/search

Search canonical entities by name or email.

Auth: Bearer token

Query Parameters
Parameter Type Description
q string Search query
class string Entity class filter
GET /api/v1/entity-registry/list

Browse all canonical entities with pagination and filtering.

Auth: Bearer token

GET /api/v1/entity-registry/by-entity/:app/:entityType/:entityId

Reverse lookup: find canonical entity from an app-specific reference.

Auth: Bearer token

GET /api/v1/entity-registry/:canonicalId

Get canonical entity by ID with all linked records.

Auth: Bearer token

GET /api/v1/entity-registry/:canonicalId/genealogy

Get the full link history (genealogy journey) for an entity.

Auth: Bearer token

GET /api/v1/entity-registry/:canonicalId/timeline

Get platform event timeline for a canonical entity.

Auth: Bearer token

GET /api/v1/entity-registry/:canonicalId/profile

Get comprehensive aggregated profile from all linked entities.

Auth: Bearer token

POST /api/v1/entity-registry/register

Register a new canonical entity with its first link.

Auth: Bearer token

Request Body
json 
{
  "name": "Jane Doe",
  "email": "jane@company.com",
  "entityClass": "person",
  "app": "sales",
  "entityType": "lead",
  "entityId": 42
}
POST /api/v1/entity-registry/link

Manually link an app entity to an existing canonical record.

Auth: Bearer token

POST /api/v1/entity-registry/merge

Merge two canonical records (loser into winner).

Auth: Bearer token

POST /api/v1/entity-registry/auto-link

Auto-find or create canonical entity by email match.

Auth: Bearer token

DELETE /api/v1/entity-registry/links/:linkId

Remove a specific entity link.

Auth: Bearer token

Platform Events

Cross-module event tracking and analytics.

POST /api/v1/platform-events

Write a single platform event.

Auth: Bearer token

Request Body
json 
{
  "canonicalId": "uuid",
  "app": "sales",
  "category": "engagement",
  "action": "email_opened",
  "metadata": {}
}
POST /api/v1/platform-events/batch

Write multiple events in batch (max 500 per request).

Auth: Bearer token

GET /api/v1/platform-events/:canonicalId

List events for a canonical entity with pagination and filters.

Auth: Bearer token

GET /api/v1/platform-events/:canonicalId/summary

Get KPI summary for a canonical entity.

Auth: Bearer token

GET /api/v1/platform-events/:canonicalId/activity-summary

Get event counts by app/category for 30/90/365-day windows.

Auth: Bearer token

Setup Hub

Guided setup wizard for new tenants.

GET /api/v1/setup-hub

Get setup progress for the current tenant.

Auth: Bearer token

PUT /api/v1/setup-hub/tasks/:taskCode

Update a setup task status.

Auth: Bearer token · tenant_admin

Request Body
json 
{
  "status": "completed"
}
POST /api/v1/setup-hub/auto-check

Run auto-detection for all checkable setup tasks.

Auth: Bearer token · tenant_admin

PUT /api/v1/setup-hub/complete

Mark overall setup as complete.

Auth: Bearer token · tenant_admin

Personal Dashboard

Aggregated action items and unread counts for the current user.

GET /api/v1/me/action-items

Get action items including tasks, overdue items, and due-soon items.

Auth: Bearer token

GET /api/v1/me/unread-counts

Get aggregated unread counts for email, tasks, chat, and notifications.

Auth: Bearer token

Health

System health and service status.

GET /api/v1/health

Health check with database connection test.

Auth: None (public)

GET /api/v1/health/system

Get infrastructure and downstream service health.

Auth: None (public)

GET /api/v1/health/services

Get aggregated downstream service health.

Auth: Bearer token