Authentication

How WatchTower separates human console access from machine-to-machine transaction ingestion.

Console access

Session-based authentication for operators working in dashboards, alerts, cases, rules, and reports.

Ingestion access

Machine-to-machine authentication for source systems sending transactions to an organization.

Security controls

MFA, recovery flows, role-based access, and server-side authorization enforcement.

Two authentication models

WatchTower uses two authentication models because operators and source systems have different security needs.

Human access

email and password login
HttpOnly session cookies
MFA for sensitive roles
role-based access inside the organization

Machine access

organization-scoped API keys
idempotent ingestion requests
backend-only key storage
audit visibility for key lifecycle changes

Console session authentication

Console users sign in with email and password without an existing session. Successful login creates an HttpOnly sessionToken cookie. MFA-enabled login returns a challenge token until verification completes.

Used for

dashboard and reporting
alerts and cases
rules and controls
team settings
notification settings
audit log review

Ingestion API-key authentication

Transaction ingestion uses an organization-scoped machine-to-machine model. This keeps source-system integration separate from user login.

Used for

/api/v1/transactions
backend and middleware integrations
simulator and controlled test traffic

Required headers

x-api-key

idempotency-key

MFA and recovery

WatchTower supports TOTP-based MFA through authenticator apps. Backup codes are issued during setup and should be stored securely by the user.

Password reset requests return a generic message. Eligible accounts receive a reset link by email. The response does not expose the reset token or link.

Authentication and recovery routes

/api/v1/auth/login
/api/v1/auth/mfa/setup
/api/v1/auth/mfa/verify-setup
/api/v1/auth/password-reset/request
/api/v1/auth/password-reset/complete
/api/v1/auth/change-password

Roles and access

Route access and operational actions are enforced server-side according to role and organization membership.

Organization roles

ADMIN
RISK_LEAD
ANALYST
VIEWER

Access principle

grant the smallest practical role
review role assignments regularly
require MFA for administrators and risk leads

Keep control surfaces separate

Use session authentication for operators and API-key authentication for ingestion. Do not reuse either surface for the other job.