SAML SSO
Configure an enterprise SAML connection and let your team sign in to the Zumik console through your identity provider, with signed-assertion verification, replay protection, and JIT provisioning.
Enterprise SSO lets your team sign in to the Zumik console through your own identity provider (Okta, Entra ID, Google Workspace, …) over SAML 2.0. You register a connection, hand the IdP Zumik's SP metadata, and your users authenticate at /auth/saml/{id}/login. Zumik verifies the IdP's signature on every assertion before establishing a session.
Connection management (/v2/sso-connections) requires an admin API key. The login flow itself (/auth/saml/...) is unauthenticated — it's the browser-facing SSO endpoints.
Register a SAML connection
POST /v2/sso-connections
protocolstringrequiredsaml.
display_namestringrequiredA label for the connection.
samlobjectrequiredidp_entity_id, idp_sso_url, and idp_certificate (the IdP's base64 X.509 signing certificate). The certificate is what assertion signatures are verified against.
jit_provisioningbooleandefault: falseCreate a user on first SSO login if their email is unknown.
The response includes the connection id (sso_...). Connections are managed with GET/DELETE /v2/sso-connections/{id}.
Hand the IdP your SP metadata
GET /v2/sso-connections/{id}/saml-metadata
Returns the Service Provider metadata XML (entity id and ACS URL) to paste into your IdP. The SP advertises AuthnRequestsSigned="false" and WantAssertionsSigned="true" — Zumik does not sign AuthnRequests, but it requires and verifies a signature on the assertion.
The login flow
Browser → GET /auth/saml/{id}/login → 302 to IdP (AuthnRequest, redirect binding)
IdP → POST /auth/saml/{id}/acs (signed SAMLResponse, RelayState)
Zumik → verify signature + conditions + replay → mint console session → 302 to consoleStart login
GET /auth/saml/{id}/login
Builds a SAML 2.0 AuthnRequest (HTTP-Redirect binding, DEFLATE-encoded), records a server-side relay-state entry to bind the eventual response to this request (InResponseTo), and 302-redirects the browser to your IdP's SSO URL.
Assertion Consumer Service
POST /auth/saml/{id}/acs
The IdP posts the form fields SAMLResponse (base64) and RelayState here. Zumik:
- Verifies the XML signature of the assertion against the connection's
idp_certificate, and validates the audience, time window, andInResponseTo. - Prevents replay — an assertion id is accepted once; a re-post is rejected.
- Establishes the session — the subject NameID (an email) is matched to a user (or provisioned when
jit_provisioningis on), and an httpOnly console session cookie is set before redirecting to the console.
A response that fails verification returns 403 with no detail; a binary built without SAML support returns 501.
Logout
GET /auth/saml/{id}/logout
Clears the console session cookie (SP-side single logout) and redirects to the console.
Errors
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | Managing connections without a valid API key. |
| 403 | insufficient_scope | Managing connections without an admin-scoped key. |
| 403 | — | An assertion failed signature/condition verification, or was replayed (login flow). |
| 404 | — | Unknown or inactive SAML connection (login flow). |
| 501 | — | The server was built without the SAML feature. |
See the full table on errors.
Billing
Read the billing account, set a monthly budget, opt into overage, start Stripe Checkout, open the customer portal, and the Stripe webhook contract.
Compliance
Read the machine-readable sub-processor list and read or update per-project privacy preferences. One source of truth behind the published legal pages.