Extension API

The Extension API provides endpoints for browser extension communication with the Surface Security backend. All endpoints are under the /api/v1/ext prefix.

Authentication

The Extension API supports two authentication methods:

1. E2E Encryption (preferred) -- Application-layer end-to-end encryption using ECDH key agreement (P-256) for body encryption (AES-256-GCM) and ECDSA (P-256) for request signing. Activates automatically when the tenant has E2E enabled and the device has a valid certificate.

2. Header-based auth (fallback) -- Uses X-Device-ID and X-Tenant-ID headers when E2E is not configured.

When E2E is active, all POST/PUT/PATCH request bodies are encrypted and sent with content type application/x-surfacesec-e2e. GET/DELETE requests use ECDSA-signed headers for authentication.

Rate Limiting

Limit	Default	Environment Variable
Requests per window	100 per 60 seconds per client	RATE_LIMIT_RPS

When rate limited, responses include a Retry-After header.

Common Error Response

{
  "error": "descriptive error message"
}

---

Event Ingestion

All event endpoints accept JSON request bodies and return {"status": "ok"} on success. No passwords or credentials are transmitted -- only metadata about authentication events.

Submit Navigation Event

POST /api/v1/ext/events/navigation

Submits a single navigation event.

Submit Navigation Events (Batch)

POST /api/v1/ext/events/navigation/batch

Submits a batch of navigation events. Maximum 50 events per request.

Submit Credential Attempt Event

POST /api/v1/ext/events/credential-attempt

Reports a credential entry event (login form interaction). Includes metadata about password reuse, HIBP status, and policy enforcement -- never the actual password.

Submit Auth Flow Event

POST /api/v1/ext/events/auth-flow

Reports authentication flow events including MFA prompts, SSO redirects, and IDP detection.

Submit MFA Enrollment Event

POST /api/v1/ext/events/mfa-enrollment

Reports observed MFA enrollment / configuration events on identity-provider pages (e.g. a user adding a new authenticator).

Submit Tech Fingerprint Event

POST /api/v1/ext/events/tech-fingerprint

Reports a single technology fingerprint detection (frameworks, libraries, services detected on visited pages).

Submit Tech Fingerprint Events (Batch)

POST /api/v1/ext/events/tech-fingerprint-batch

Submits a batch of technology fingerprint events.

Submit Phishing Detection Event

POST /api/v1/ext/events/phishing-detection

Reports a phishing detection event with confidence scoring, detection signals (pHash, form analysis, domain analysis), and optional screenshot hash.

Submit AiTM Detection Event

POST /api/v1/ext/events/aitm-detection

Reports an Adversary-in-the-Middle detection event. Includes detection type (evilginx, evilnovnc, muraena, modlishka, unknown), confidence score, and indicators.

Submit Clipboard Threat Event

POST /api/v1/ext/events/clipboard-threat

Reports clipboard-based attack detections including ClickFix, FileFix, crypto clippers, and pastejacking attempts.

Submit GenAI Activity Event

POST /api/v1/ext/events/genai-activity

Reports data loss prevention events related to GenAI tools -- detects PII, code, or large text submissions to AI services.

Submit DLP Activity Event

POST /api/v1/ext/events/dlp-activity

Reports general data-loss-prevention events detected by the extension (paste/copy of sensitive content, sensitive content typed into disallowed destinations, etc.).

Submit Screen Capture Event

POST /api/v1/ext/events/screen-capture

Reports screen sharing or display capture activity (screen_share, display_media, tab_capture).

Submit Download Events (Batch)

POST /api/v1/ext/events/download/batch

Submits a batch of download events with risk assessment. Maximum 50 events per request.

Submit Print Event

POST /api/v1/ext/events/print

Reports print activity for DLP monitoring.

Submit HTML Smuggling Event

POST /api/v1/ext/events/html-smuggling

Reports HTML smuggling detection events (Blob URL downloads with login form indicators).

Submit OAuth Threat Event

POST /api/v1/ext/events/oauth-threat

Reports malicious OAuth consent phishing detections (rogue consent screens, suspicious scopes on third-party apps).

Submit Web Skimmer Event

POST /api/v1/ext/events/skimmer-alert

Reports JavaScript-based web skimmer / card-stealing behavior observed on a page.

Submit Shadow State Mesh Event

POST /api/v1/ext/events/shadow-state-mesh

Reports cross-origin state-leak detections from the shadow-state mesh detector.

Submit Key Rotated Event

POST /api/v1/ext/events/key-rotated

Notifies the backend that the extension has rotated its local ECDH/ECDSA keypair so subsequent E2E traffic can be verified against the new key material.

Submit Agentic Session Event

POST /api/v1/ext/events/agentic-session

Reports the start / end of an AI agent browsing session (see agentic security mode).

Submit Agentic Alert Batch

POST /api/v1/ext/events/agentic-alert/batch

Batch endpoint for agentic-mode alerts (policy violations observed while an AI agent is driving the browser).

---

Policy Sync

Get Security Policies

GET /api/v1/ext/policies

Returns the current security policies for the device's tenant. The extension polls this endpoint periodically to receive updated policy rules and configuration.

This endpoint also distributes the E2E channel public key when E2E encryption is enabled for the tenant.

---

Heartbeat

Device Heartbeat

POST /api/v1/ext/heartbeat

Returns the device's current health status, checks for pending actions (e.g., remote wipe signal), and can transparently renew the device certificate before expiry. The extension calls this periodically.

GET /api/v1/ext/heartbeat is also accepted for backward compatibility and logs a deprecation warning; new clients should use POST.

Extended Heartbeat (Deprecated)

POST /api/v1/ext/heartbeat-extended

Deprecated alias that delegates to POST /api/v1/ext/heartbeat. Retained for older extension builds.

Certificate Renewal

POST /api/v1/ext/certificate/renew

Issues a replacement device certificate. Normally the heartbeat endpoint renews certificates automatically; this endpoint is a fallback the extension calls when it misses a renewal window (e.g. the device was offline).

---

Extension Stats

Get Extension Stats

GET /api/v1/ext/stats

Returns statistics for the extension popup UI (e.g., events sent, policy status, alerts).

---

Phishing Data

Sync Phishing Data

GET /api/v1/ext/phishing/sync

Returns phishing detection data including known-good baselines, whitelist entries, and detection thresholds.

Report Phishing

POST /api/v1/ext/phishing/report

Submits a user-initiated phishing report for a suspicious page.

Request Domain Access

POST /api/v1/ext/phishing/request-access

Submits a request to unblock a domain that was blocked by phishing detection. Creates a pending approval in the admin dashboard.

---

Signatures

Get Phishing Signatures

GET /api/v1/ext/signatures

Returns the current phishing detection signatures for the extension (visual clone detection, form fingerprints, etc.).

Get ClickFix Signatures

GET /api/v1/ext/clickfix-signatures

Returns ClickFix/FileFix detection signatures for identifying clipboard-based social engineering attacks.

---

Screenshots

Upload Phishing Screenshot

POST /api/v1/ext/screenshots

Uploads a screenshot captured during a phishing detection event.

Body:

{
  "eventId": "uuid",
  "origin": "https://suspicious-site.com",
  "screenshotHash": "perceptual-hash-value",
  "imageData": "base64-encoded-jpeg"
}

Response:

{
  "screenshotID": "uuid"
}

Screenshots are stored in MinIO object storage and accessible via presigned URLs through the Admin API.

---

Domain Scans

Check Domain Scan Status

GET /api/v1/ext/domain-scans/{domain}

Checks whether a domain needs scanning by third-party threat intelligence services.

Response:

{
  "domain": "suspicious-site.com",
  "urlscanLastScannedAt": "2024-01-10T00:00:00Z",
  "urlscanIsMalicious": false,
  "vtLastScannedAt": "2024-01-10T00:00:00Z",
  "vtMaliciousCount": 0
}

Fields are omitted if the domain has never been scanned by that service. Domains are re-scanned if the last scan is older than 7 days.

Report Domain Scan Results

POST /api/v1/ext/domain-scans

Reports scan results from a third-party threat intelligence service.

Body (URLScan):

{
  "domain": "suspicious-site.com",
  "service": "urlscan",
  "isMalicious": true,
  "score": 85
}

Body (VirusTotal):

{
  "domain": "suspicious-site.com",
  "service": "virustotal",
  "maliciousCount": 5,
  "vendorCount": 72
}

The service field must be urlscan or virustotal.

Check Domain Reputation

POST /api/v1/ext/domain-scans/check

Requests an on-demand reputation check for a domain using configured threat intelligence services.

---

Baselines

Submit Baseline Fingerprint

POST /api/v1/ext/baselines

Submits a baseline fingerprint for an authentication endpoint (used for visual clone detection).

Sync Baselines

GET /api/v1/ext/baselines/sync

Returns the current baseline fingerprints for the tenant's known-good authentication endpoints.

Sync Baselines (Delta)

GET /api/v1/ext/baselines/delta

Returns only the baseline fingerprints that have changed since the extension's last sync. Extensions should prefer this endpoint over baselines/sync once they have an initial snapshot.

Query Parameters:

Parameter	Type	Description
since	string	RFC 3339 timestamp of the extension's last successful sync

---

Extension Monitoring

Get Extension Whitelist

GET /api/v1/ext/extensions/whitelist

Returns the approved browser extension whitelist for enforcement by the extension.

Report Extension Inventory

POST /api/v1/ext/extensions/inventory

Reports the full list of installed browser extensions on the device.

Report Extension Events

POST /api/v1/ext/extensions/events

Reports extension lifecycle events (installs, uninstalls, permission changes).

---

Update Check

Check for Extension Updates

GET /api/v1/ext/update-check

Returns update information if a newer extension version is available.

Query Parameters:

Parameter	Type	Description
version	string	Current extension version
channel	string	Update channel (e.g., stable, beta)

---

Verification

The verification system enables peer-to-peer identity verification between employees using daily codes and one-time passwords.

Register Device Keypair

POST /api/v1/ext/verification/keypair

Registers a device's public key for the verification system.

Daily Code Challenge

POST /api/v1/ext/verification/daily-code/challenge

Requests a daily code challenge for identity verification.

Read Daily Code

POST /api/v1/ext/verification/daily-code/read

Reads the current daily code for the authenticated user.

Verify Daily Code

POST /api/v1/ext/verification/daily-code/verify

Verifies a daily code provided by another user.

Create OTP

POST /api/v1/ext/verification/otp/create

Creates a one-time password for sharing with another user for verification.

Verify OTP

POST /api/v1/ext/verification/otp/verify

Verifies a one-time password received from another user.

List Active OTPs

GET /api/v1/ext/verification/otp/active

Returns the list of active (unexpired) one-time passwords for the authenticated user.

Search Users for Verification

GET /api/v1/ext/verification/users

Query Parameters:

Parameter	Type	Description
email	string	Email address to search for

Log Verification Event

POST /api/v1/ext/verification/events

Logs an extension-side verification event (complements server-side logging) so the dashboard timeline captures UI-level context (e.g. "code displayed to user at T").

List Verification Alerts

GET /api/v1/ext/verification/alerts

Returns verification-related alerts for the authenticated user.

Mark Verification Alert Read

PUT /api/v1/ext/verification/alerts/{alertID}/read

---

Unblock Keys

Unblock keys allow temporary bypass of blocked domains for authorized users.

Verify Unblock Key

POST /api/v1/ext/unblock-keys/verify

Checks whether an unblock key is valid without consuming it.

Use Unblock Key

POST /api/v1/ext/unblock-keys/use

Consumes an unblock key to temporarily bypass a domain block.

---

Agentic Security Mode

Endpoints consumed by the extension when an AI browsing agent is driving the browser. See Agentic Security Mode for the admin-side configuration.

Fetch Agentic Config

POST /api/v1/ext/agentic/config

Returns the tenant's current agentic-mode configuration (allowed sites, policy flags, provider fingerprints). Sent as POST so the extension can submit the agent-detection context that produced the request.