SafeWeb API Documentation
Overview
SafeWeb exposes two authenticated REST APIs for integrations, plus guides for signing customers into the portal.
| API | Base path | Who it's for |
|---|---|---|
| Partner API | /api/v1/integrations/... | Integration partners managing end customers, breach data, analytics, and event delivery |
| Distributor API | /api/v1/distributors/... | Distributors managing partner organizations, billing codes, memberships, and distributor-scoped event delivery |
Partners onboard customers, configure monitored assets, retrieve breach intelligence, access account-level analytics, and register HTTPS callback URLs. Distributors operate one level above partners — creating and managing partner organizations, billing codes, team memberships, and distributor-level analytics.
Customer portal sign-in is documented separately under SSO: enterprise IdP (SAML 2.0, configured on request) or magic link via the Partner API.
Quick Start
- Get your credentials — contact SafeWeb to receive Partner credentials (
SW-PARTNER-ID/SW-API-KEY) and/or Distributor credentials (SW-DISTRIBUTOR-ID/SW-API-KEY) - Verify connectivity — call the health check endpoint
- Test in staging — use the staging base URL below; if you implement HTTP callbacks, read Outbound webhooks for signatures, payloads, and retries
- Go live — switch to the production base URL
Environments
| Environment | Base URL |
|---|---|
| Staging | https://staging-connect.safeweb.co |
| Production | https://connect.safeweb.co |
Use the staging environment for development and testing. Both environments behave identically.
API reference
General
Health check
Confirm the API is reachable and returns a health payload.
Breach categories
List breach category metadata used in breach responses.
Partner API
Customer lifecycle, breach intelligence, partner analytics, and partner-scoped event delivery.
Partner API overview
Authentication, customer management, breach endpoints, and webhooks.
Onboard customer
Create a customer and configure initial monitoring.
Customer breaches
Retrieve breach status and records for a customer.
Partner analytics
Partner-level metrics and aggregate usage insights.
Distributor API
Analytics, billing codes, partner organizations, memberships, and distributor-scoped event delivery.
Distributor API overview
Authentication, partner management, billing codes, and webhooks.
Distributor analytics
Distributor-level performance and activity metrics.
Partners
List and create partner organizations under your distributor.
Partner memberships
List memberships and invite members to a partner organization.
Customer authentication (SSO)
Sign in end customers via enterprise IdP (configured on request) or magic link through the Partner API.
SSO overview
Compare enterprise SSO and magic link sign-in for customers.
Enterprise SSO
Corporate IdP sign-in via SAML 2.0 — configured by SafeWeb on request.
Magic link
Request a one-time login URL for a customer via the Partner API.
Outbound webhooks
SafeWeb POSTs signed JSON events to HTTPS URLs you register. The wire protocol is shared; management APIs differ by scope.
Outbound webhooks reference
Delivery protocol: signatures, payloads, retries, and event catalogue.
Partner event delivery
Register and manage webhook URLs for your partner organization.
Distributor event delivery
Register and manage webhook URLs at distributor scope.
Core concepts
Customers
A customer represents an end user being monitored. Each customer record includes:
- Contact details — name and email address
- Monitored assets — one or more domains, email addresses, or both
- Plan — determines features and monitoring level
- Billing configuration — currency, billing date, and pricing tier
Once onboarded, SafeWeb handles email discovery, breach scanning, alerts, and reporting automatically.
Plans
| Plan | Description |
|---|---|
safeweb-basic | Dark web monitoring with breach alerts |
safeweb-plus | Everything in Basic, plus a customer self-service portal and monthly security reports |
Monitored assets
SafeWeb monitors two types of assets per customer:
- Domains — associated email addresses are discovered automatically and monitored for breaches
- Email addresses — monitored directly against breach databases
At least one domain or email address must be provided when onboarding a customer. Monitoring runs on a daily schedule and requires no further API interaction once configured.