Single sign-on (SSO)
Overview
| Option | Best for |
|---|---|
| Enterprise SSO | Customers who must authenticate through your corporate identity provider (SAML 2.0) |
| Magic link | Embedded or partner-hosted flows where you obtain a one-time login URL via the Partner API |
Both paths result in a standard
Choosing an approach
| Consideration | Enterprise SSO | Magic link |
|---|---|---|
| Setup | Configured by | Self-serve via Partner API |
| Customer experience | Sign in at your IdP (Okta, Entra, etc.) | Open a one-time URL you deliver from your app |
| Policy control | MFA, conditional access, and session rules at your IdP | Link expiry and portal session limits on |
| Typical use | Mandated corporate IdP, regulated industries | “Open dashboard” from your portal, post-onboarding deep links |
You can use both for different customer segments. Enterprise SSO does not replace the magic link API for partners who need programmatic sign-in from their own applications.
Terminology
| Term | Meaning |
|---|---|
| Customer | End user monitored on |
| Partner | Your integration organization. Authenticates Partner API calls with SW-PARTNER-ID and SW-API-KEY. |
| Session | Authenticated state in the customer portal, backed by access and refresh tokens. |
| Magic link | A passwordless, one-time sign-in link. Opening it verifies a token and creates a session. |
| Enterprise SSO | Sign-in through your IdP using SAML 2.0. |
| IdP | Identity provider — your SSO system (e.g. Okta, Microsoft Entra, Google Workspace). |
| SP | Service provider — |
| Assertion | Signed statement from your IdP about the authenticated user (identity, email, optional attributes). |
| NameID | Stable identifier for the user in the SAML assertion, often their email address. |
| ACS URL | Endpoint where your IdP sends the SAML response after the user signs in. |
Sessions
After either sign-in method succeeds, the customer receives a portal session:
- Access tokens are short-lived (typically one hour). The portal refreshes the session using a refresh token while the customer remains active.
- Enterprise SSO sessions may also be limited by your IdP (session lifetime, forced re-authentication, or group policy).
honours those limits when the IdP enforces them. - Sign-out from the portal ends the
session. Single logout (SLO) back to your IdP is not supported; customers who need to re-authenticate should sign out of the portal or rely on IdP session policies.
How it fits together
Magic link (Partner API)
flowchart LR
partner[Partner backend]
api[Partner API]
auth[Auth service]
portal[Customer portal]
partner -->|"magic link request"| api
api -->|"create magic link"| auth
api -->|"returns url"| partner
partner -->|"deliver url to customer"| portal
portal -->|"verify token"| authEnterprise SSO
sequenceDiagram
participant Customer
participant Portal as Customer portal
participant IdP as Your IdP
Customer->>Portal: Sign in with SSO
Portal->>IdP: Redirect (SAML AuthnRequest)
IdP->>Customer: Authenticate (MFA, policy, etc.)
IdP->>Portal: SAML assertion (ACS)
Portal->>Customer: Session establishedFor enterprise SSO, the customer is redirected to your IdP instead of using the magic link API.
Guides
Enterprise SSO
Sign in customers through your corporate IdP. Configured on request.
Magic link
Request a one-time login URL for a customer via the Partner API.
Partner API authentication
Magic link generation uses the same headers as other /api/v1/integrations/... endpoints. See the Partner API overview for credentials and environment URLs.
Get breach categories GET
Returns the list of breach categories used to classify types of data exposed in breaches. Requires authentication via SW-PARTNER-ID and SW-API-KEY headers. Accepts a partner or distributor API key.
Enterprise SSO
Sign in customers through your corporate identity provider. Each deployment is configured on request.