{"openapi":"3.0.3","info":{"title":"SpoofSentry API","version":"3.1.0","description":"Enterprise DMARC monitoring and email security platform API. Provides domain monitoring, authentication analytics, BIMI certificate management, and outbound integrations.","contact":{"name":"DomainSeal Labs","email":"support@domainseal.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"/api","description":"API base path"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Session token from cookie or Authorization header"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"spoofsentry_session"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid request"},"details":{"type":"array","items":{"type":"object"}}}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"pageSize":{"type":"integer","example":20},"total":{"type":"integer","example":42},"totalPages":{"type":"integer","example":3}}},"Domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"example.com"},"status":{"type":"string","enum":["pending","verified","failed"]},"dmarcRecord":{"type":"string","nullable":true},"spfRecord":{"type":"string","nullable":true},"dkimSelector":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Alert":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dmarc_failure","spf_failure","dkim_failure","new_sender","policy_change","verification_expired"]},"severity":{"type":"string","enum":["low","medium","high","critical"]},"title":{"type":"string"},"message":{"type":"string"},"acknowledged":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"BimiProduct":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["digicert","entrust"]},"name":{"type":"string"},"priceUsd":{"type":"number"},"validityMonths":{"type":"integer"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"failCount":{"type":"integer"},"lastFailedAt":{"type":"string","format":"date-time","nullable":true},"lastSucceededAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"statusCode":{"type":"integer","nullable":true},"latencyMs":{"type":"integer","nullable":true},"attempt":{"type":"integer"},"success":{"type":"boolean"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"IntegrationConfig":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["slack","jira","teams","pagerduty"]},"enabled":{"type":"boolean"},"webhookUrl":{"type":"string","format":"uri","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AnalyticsEnvelope":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"timezone":{"type":"string","example":"America/New_York"},"data":{"type":"object"}}}},"parameters":{"periodParam":{"in":"query","name":"period","schema":{"type":"string","enum":["7d","30d","90d"],"default":"30d"},"description":"Time period for analytics queries"},"timezoneParam":{"in":"query","name":"timezone","schema":{"type":"string","default":"UTC"},"description":"IANA timezone for date grouping"}}},"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"tags":[{"name":"Auth","description":"Authentication & session management"},{"name":"Domains","description":"Domain monitoring management"},{"name":"Reports","description":"DMARC report aggregation"},{"name":"Alerts","description":"Security alert management"},{"name":"BIMI","description":"BIMI certificate management"},{"name":"Analytics","description":"Real-time analytics & metrics"},{"name":"Billing","description":"Subscription & payment management"},{"name":"Integrations","description":"Third-party integration configuration"},{"name":"Webhooks","description":"Outbound webhook endpoint management"},{"name":"MSSP","description":"Managed security service provider operations"}],"paths":{"/alerts":{"get":{"tags":["Alerts"],"summary":"List alerts","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"severity","schema":{"type":"string","default":1,"enum":["low","medium","high","critical"]}},{"in":"query","name":"acknowledged","schema":{"type":"boolean","default":20}},{"in":"query","name":"unread","schema":{"type":"string","enum":["true","false"]},"description":"Filter to unread alerts only"}],"responses":{"200":{"description":"Alert list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/{id}/read":{"patch":{"tags":["Alerts"],"summary":"Mark an alert as read","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Alert ID"}],"responses":{"200":{"description":"Alert marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Alert"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Alert not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/read-all":{"post":{"tags":["Alerts"],"summary":"Mark all alerts as read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"All alerts marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/overview":{"get":{"tags":["Analytics"],"summary":"Overview summary cards (domains, emails, pass rate, alerts)","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Number of days to look back","$ref":"#/components/parameters/periodParam"},{"in":"query","name":"tz","schema":{"type":"string","default":"UTC"},"description":"IANA timezone","$ref":"#/components/parameters/timezoneParam"}],"responses":{"200":{"description":"Analytics overview","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyticsEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"verifiedDomains":{"type":"integer"},"totalDomains":{"type":"integer"},"totalEmails":{"type":"integer"},"passRate":{"type":"number"},"failRate":{"type":"number"},"quarantineRate":{"type":"number"}}}}}],"$ref":"#/components/schemas/AnalyticsEnvelope"}}}},"400":{"description":"Invalid timezone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/email-trends":{"get":{"tags":["Analytics"],"summary":"Email volume & pass rate time series","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Number of days to look back","$ref":"#/components/parameters/periodParam"},{"in":"query","name":"tz","schema":{"type":"string","default":"UTC"},"description":"IANA timezone for date grouping","$ref":"#/components/parameters/timezoneParam"}],"responses":{"200":{"description":"Time series data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyticsEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"trends":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"total":{"type":"integer"},"passed":{"type":"integer"},"failed":{"type":"integer"}}}}}}}}]}}}},"400":{"description":"Invalid timezone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/sender-reputation":{"get":{"tags":["Analytics"],"summary":"Sender trust scores & authentication rates","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Number of days to look back","$ref":"#/components/parameters/periodParam"},{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100},"description":"Max senders to return","$ref":"#/components/parameters/timezoneParam"}],"responses":{"200":{"description":"Sender reputation data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyticsEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"senders":{"type":"array","items":{"type":"object","properties":{"orgName":{"type":"string"},"totalEmails":{"type":"integer"},"passCount":{"type":"integer"},"passRate":{"type":"number"}}}}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics/domain-health":{"get":{"tags":["Analytics"],"summary":"Per-domain DNS record status & compliance","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Domain health data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyticsEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"domainName":{"type":"string"},"status":{"type":"string"},"bimiReady":{"type":"boolean"},"hasDmarc":{"type":"boolean"},"hasSpf":{"type":"boolean"},"hasDkim":{"type":"boolean"},"reportCount":{"type":"integer"},"passRate":{"type":"number"},"lastReportDate":{"type":"string","format":"date-time","nullable":true}}}}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/periodParam"},{"$ref":"#/components/parameters/timezoneParam"}]}},"/analytics/bimi-stats":{"get":{"tags":["Analytics"],"summary":"BIMI order pipeline & certificate status","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"BIMI statistics","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyticsEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"byStatus":{"type":"object","additionalProperties":{"type":"integer"}},"totalOrders":{"type":"integer"},"totalMarginCents":{"type":"integer"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/periodParam"},{"$ref":"#/components/parameters/timezoneParam"}]}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Request a magic link for login","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Magic link sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/verify":{"post":{"tags":["Auth"],"summary":"Verify a magic link and create a session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Session created, cookie set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"user":{"type":"object"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/signup":{"post":{"tags":["Auth"],"summary":"Create a new account and send magic link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","companyName"],"properties":{"email":{"type":"string","format":"email"},"companyName":{"type":"string","minLength":1,"maxLength":100},"userName":{"type":"string","minLength":1,"maxLength":100}}}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Email already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/signup/mssp":{"post":{"tags":["Auth"],"summary":"Submit an MSSP application (pending admin approval)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","companyName"],"properties":{"email":{"type":"string","format":"email"},"companyName":{"type":"string"},"userName":{"type":"string"},"companyWebsite":{"type":"string","format":"uri"},"estimatedCustomerCount":{"type":"integer"}}}}}},"responses":{"201":{"description":"Application submitted"},"400":{"description":"Validation error"},"409":{"description":"Email already exists or application already pending"},"429":{"description":"Rate limit exceeded"}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Clear the session cookie","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Logged out successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}},"/auth/me":{"get":{"tags":["Auth"],"summary":"Get current user info with MSSP context","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current user details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"actorTenantId":{"type":"string"},"activeTenantId":{"type":"string"},"isMsspActor":{"type":"boolean"},"tenantId":{"type":"string"}}},"accessibleTenants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/active-tenant":{"post":{"tags":["Auth"],"summary":"Switch active tenant (MSSP customer switcher)","description":"Re-mints the JWT with a different activeTenantId. Requires MSSP role.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant switched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"activeTenantId":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - cross-tenant access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Tenant not found or suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/magic-link":{"post":{"tags":["Auth"],"summary":"Request a magic link (legacy endpoint)","deprecated":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Magic link sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create Stripe checkout session","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["priceId"],"properties":{"plan":{"type":"string","enum":["starter","pro","enterprise"]},"priceId":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout session URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"sessionId":{"type":"string"}}}}}}}},"400":{"description":"Invalid plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner or admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/portal":{"post":{"tags":["Billing"],"summary":"Create Stripe customer portal session","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Portal session URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}}}},"403":{"description":"Owner or admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/subscription":{"get":{"tags":["Billing"],"summary":"Get current subscription status","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"plan":{"type":"object"},"subscription":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/cancel":{"post":{"tags":["Billing"],"summary":"Cancel subscription at end of billing period","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Subscription cancellation scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"403":{"description":"Owner role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active subscription found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/reactivate":{"post":{"tags":["Billing"],"summary":"Reactivate a subscription set to cancel","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Subscription reactivated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"400":{"description":"Subscription is not set to cancel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No subscription found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/billing/usage":{"get":{"tags":["Billing"],"summary":"Get usage summary for current billing period","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/admin/pending-orders":{"get":{"tags":["BIMI"],"summary":"List BIMI orders needing admin action","description":"Platform admin endpoint to list orders across all tenants that need processing.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["paid","submitted","validation","issued","rejected"],"default":"paid"},"description":"Filter by order status"}],"responses":{"200":{"description":"List of pending orders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Platform admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/admin/orders/{id}/status":{"post":{"tags":["BIMI"],"summary":"Transition a BIMI order's status","description":"Platform admin endpoint to update order status with valid state transitions.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Order ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["submitted","validation","issued","active","rejected","refunded"]},"providerOrderId":{"type":"string"},"rejectionReason":{"type":"string"}}}}}},"responses":{"200":{"description":"Order status updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"description":"Invalid status transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Platform admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/products":{"get":{"tags":["BIMI"],"summary":"List VMC certificate products & pricing","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BimiProduct"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/readiness/{domainId}":{"get":{"tags":["BIMI"],"summary":"Check BIMI readiness for a domain","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"domainId","required":true,"schema":{"type":"string"},"description":"Domain ID"}],"responses":{"200":{"description":"Readiness assessment with score","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ready":{"type":"boolean"},"checks":{"type":"object"},"dnsRecord":{"type":"string","nullable":true},"activeOrder":{"type":"object","nullable":true}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/validate-logo":{"post":{"tags":["BIMI"],"summary":"Validate logo URL for BIMI compliance","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["logoUrl"],"properties":{"logoUrl":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"logoUrl is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/checkout":{"post":{"tags":["BIMI"],"summary":"Purchase VMC certificate via Stripe checkout","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId","domainId","logoUrl"],"properties":{"domainId":{"type":"string"},"provider":{"type":"string","enum":["digicert","entrust"]},"logoUrl":{"type":"string","format":"uri"},"productId":{"type":"string"}}}}}},"responses":{"200":{"description":"Stripe checkout session URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri"},"sessionId":{"type":"string"},"orderId":{"type":"string"}}}}}}}},"400":{"description":"Validation error or domain not eligible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/orders":{"get":{"tags":["BIMI"],"summary":"List certificate orders","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Order list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"domainName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"statusLabel":{"type":"string"},"statusColor":{"type":"string"},"priceCents":{"type":"integer"},"priceFormatted":{"type":"string"},"logoUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"issuedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bimi/orders/{id}":{"get":{"tags":["BIMI"],"summary":"Get order details with DNS records","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Order ID"}],"responses":{"200":{"description":"Order details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"domainName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"statusLabel":{"type":"string"},"statusColor":{"type":"string"},"priceCents":{"type":"integer"},"dnsRecord":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains":{"get":{"tags":["Domains"],"summary":"List monitored domains","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Paginated domain list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean"}},"items":{"$ref":"#/components/schemas/Domain"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Domains"],"summary":"Add a new domain","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"domainName":{"type":"string","example":"example.com"},"name":{"type":"string","example":"example.com"}}}}}},"responses":{"201":{"description":"Domain created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}/verify":{"post":{"tags":["Domains"],"summary":"Verify DNS records for domain","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Domain ID"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/Domain"},"verified":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{id}":{"delete":{"tags":["Domains"],"summary":"Remove domain","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Domain ID"}],"responses":{"200":{"description":"Domain deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Domains"],"summary":"Get domain details","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Domain details"},"404":{"description":"Domain not found"}}},"put":{"tags":["Domains"],"summary":"Update domain","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dmarcRecord":{"type":"string"},"spfRecord":{"type":"string"}}}}}},"responses":{"200":{"description":"Domain updated"}}}},"/mssp/customers":{"get":{"tags":["MSSP"],"summary":"List managed customer tenants","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"search","schema":{"type":"string","default":1}},{"in":"query","name":"status","schema":{"type":"string","default":20,"maximum":100,"enum":["active","suspended"]}},{"in":"query","name":"page","schema":{"type":"integer","enum":["active","suspended"],"default":1}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by company name"}],"responses":{"200":{"description":"Customer tenant list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"items":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"MSSP role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["MSSP"],"summary":"Create new customer tenant","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companyName","adminEmail"],"properties":{"companyName":{"type":"string","minLength":1,"maxLength":100},"adminEmail":{"type":"string","format":"email"},"plan":{"type":"string","enum":["free","starter","pro","enterprise"],"default":"free"}}}}}},"responses":{"201":{"description":"Customer tenant created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"customer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"plan":{"type":"string"},"linkId":{"type":"string"},"adminUser":{"type":"object","nullable":true}}}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"MSSP admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate tenant or email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mssp/customers/{id}":{"patch":{"tags":["MSSP"],"summary":"Suspend or reactivate customer","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Customer tenant ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"status":{"type":"string","enum":["active","suspended"]},"action":{"type":"string","enum":["suspend","reactivate"]}}}}}},"responses":{"200":{"description":"Customer status updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"MSSP admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["MSSP"],"summary":"Unlink customer (mssp_owner only)","description":"Removes the MSSP link and billing ownership. The tenant continues to exist as self-managed. Requires mssp_owner role.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Customer tenant ID"}],"responses":{"200":{"description":"Customer unlinked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"403":{"description":"mssp_owner role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports":{"get":{"tags":["Reports"],"summary":"List DMARC reports","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20}},{"in":"query","name":"domainId","schema":{"type":"string"},"description":"Filter by domain ID"}],"responses":{"200":{"description":"Paginated report list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/stats":{"get":{"tags":["Reports"],"summary":"Report statistics","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30},"description":"Number of days to look back"}],"responses":{"200":{"description":"Aggregate report stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"totalEmails":{"type":"integer"},"dkimPass":{"type":"integer"},"spfPass":{"type":"integer"},"rejected":{"type":"integer"},"quarantined":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/senders":{"get":{"tags":["Reports"],"summary":"Get unique email senders","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Top senders by volume","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"sourceIp":{"type":"string"},"orgName":{"type":"string"},"totalEmails":{"type":"integer"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/dmarc":{"post":{"tags":["Webhooks"],"summary":"Receive inbound DMARC reports","description":"Webhook endpoint for receiving DMARC reports from email gateway or aggregation service. Validates HMAC-SHA256 signature.","parameters":[{"in":"header","name":"x-signature","schema":{"type":"string"},"description":"HMAC-SHA256 signature of the request body"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reportId","domainName","records"],"properties":{"reportId":{"type":"string"},"domainName":{"type":"string"},"orgName":{"type":"string"},"email":{"type":"string"},"dateRangeBegin":{"type":"string","format":"date-time"},"dateRangeEnd":{"type":"string","format":"date-time"},"records":{"type":"array","items":{"type":"object","properties":{"sourceIp":{"type":"string"},"count":{"type":"integer"},"disposition":{"type":"string","enum":["none","quarantine","reject"]},"dkim":{"type":"string","enum":["pass","fail","neutral"]},"spf":{"type":"string","enum":["pass","fail","neutral"]}}}}}}}}},"responses":{"200":{"description":"Report processed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"recordsProcessed":{"type":"integer"},"alertsCreated":{"type":"integer"}}}}}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/dmarc/test":{"get":{"tags":["Webhooks"],"summary":"Test DMARC webhook endpoint accessibility","responses":{"200":{"description":"Webhook endpoint is active","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}}}}},"/reports/{id}":{"get":{"tags":["Reports"],"summary":"Get report details","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report details"},"404":{"description":"Report not found"}}}},"/alerts/{id}":{"get":{"tags":["Alerts"],"summary":"Get alert details","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alert details"},"404":{"description":"Alert not found"}}}},"/alerts/{id}/acknowledge":{"post":{"tags":["Alerts"],"summary":"Acknowledge alert","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alert acknowledged"}}}},"/integrations":{"get":{"tags":["Integrations"],"summary":"List all integrations","responses":{"200":{"description":"Integration list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationConfig"}}}}}}}}}},"/integrations/{provider}":{"get":{"tags":["Integrations"],"summary":"Get integration config (secrets masked)","parameters":[{"in":"path","name":"provider","required":true,"schema":{"type":"string","enum":["slack","jira","teams","pagerduty"]}}],"responses":{"200":{"description":"Integration config"},"404":{"description":"Integration not configured"}}},"put":{"tags":["Integrations"],"summary":"Upsert integration config","parameters":[{"in":"path","name":"provider","required":true,"schema":{"type":"string","enum":["slack","jira","teams","pagerduty"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"webhookUrl":{"type":"string","format":"uri","nullable":true},"subscribedEvents":{"type":"array","items":{"type":"string"}},"config":{"type":"object"}}}}}},"responses":{"200":{"description":"Integration saved"},"403":{"description":"Admin role required"}}},"delete":{"tags":["Integrations"],"summary":"Remove integration","parameters":[{"in":"path","name":"provider","required":true,"schema":{"type":"string","enum":["slack","jira","teams","pagerduty"]}}],"responses":{"200":{"description":"Integration removed"},"404":{"description":"Integration not found"}}}},"/integrations/{provider}/test":{"post":{"tags":["Integrations"],"summary":"Send test message to integration","parameters":[{"in":"path","name":"provider","required":true,"schema":{"type":"string","enum":["slack","jira","teams","pagerduty"]}}],"responses":{"200":{"description":"Test result"},"404":{"description":"Integration not configured"}}}},"/webhook-endpoints":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","responses":{"200":{"description":"Webhook endpoint list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Create webhook endpoint","description":"Creates a new webhook endpoint with auto-generated HMAC-SHA256 signing secret. The secret is returned in plaintext ONCE on creation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":500},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Endpoint created with signing secret"},"403":{"description":"Admin role required"}}}},"/webhook-endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Get webhook endpoint details","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint details"},"404":{"description":"Endpoint not found"}}},"patch":{"tags":["Webhooks"],"summary":"Update webhook endpoint","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Endpoint updated"},"403":{"description":"Admin role required"}}},"delete":{"tags":["Webhooks"],"summary":"Delete webhook endpoint","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint deleted"},"403":{"description":"Admin role required"}}}},"/webhook-endpoints/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List delivery history","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Delivery history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}}}}},"/webhook-endpoints/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send test event to webhook endpoint","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test delivery result"}}}},"/webhook-endpoints/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate signing secret","description":"Generates a new HMAC-SHA256 signing secret. The new secret is returned in plaintext once.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"New signing secret"},"403":{"description":"Admin role required"}}}}}}