The SAML SSO round-trip

These four operations are the service-provider side of SAML 2.0 SSO — the route an organization’s IdP administrators walk to wire Okta, Entra ID, or similar into Orbit’s sign-in. The page’s {orgSlug} path segment selects the SAML configuration; it is a URL-safe organization slug, not an API-key credential, and the operations are deliberately unauthenticated because they begin a session rather than require one. Sequence the round-trip like this. (1) GET /auth/saml/{orgSlug}/metadata returns the service-provider XML the IdP admin imports to register Orbit: entity ID, ACS URL, and signing details. (2) GET /auth/saml/{orgSlug}/login?redirect=/settings/team issues the SP-initiated AuthnRequest and 302-redirects the browser to the IdP’s SSO URL; any redirect value is signed into RelayState and sweeps the post-auth destination back. (3) The IdP POSTs the signed SAMLResponse to /auth/saml/{orgSlug}/callback — the Assertion Consumer Service verifies signature, audience, and the replay window, provisions the user on first login, then 302-redirects to the dashboard sign-in ticket that mints the session cookie. (4) GET /auth/saml/{orgSlug}/logout?nameId=<subject> builds a LogoutRequest for the IdP’s SLO endpoint when single logout is configured; otherwise it answers 200 with a logged_out status, and the local ceremony destroys the session. A worked check-in sequence in cURL:

cURL

# 1. Hand this metadata to the IdP admin
curl "https://api.orbit.devotel.io/auth/saml/acme-inc/metadata"

# 2. Start SSO — the browser redirects to the IdP
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/login?redirect=/settings/team"

# 3. The IdP POSTs here on its own — no API key involved
#    POST /auth/saml/acme-inc/callback

# 4. Log out (with the subject's NameID when available)
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/logout?nameId=user@acme.example"

The four calls above do not return the normal JSON envelope — skip the read-ahead envelope check for them. Success on this page is a 302 redirect (login, logout, and the IdP-driven callback) or a Content-Type: application/xml metadata download (metadata), not a { "data": … } body. Only failures come back in the standard { "error": …, "meta": { "request_id" } } envelope (see the error shapes table) — or, when single logout is not configured on the org, logout answers 200 with { "data": { "status": "logged_out" } }, the one non-error JSON body on this page.

The first event and the first callback are both redirect-only flows — do not call them from your application; point users at them or let the IdP drive the callback.

Same round-trip from an SDK escape hatch

The SAML ceremonies are browser-first, so no SDK ships a typed helper for them — the Node, Python, and Go SDKs all reach the same four routes through their generic request escape hatch (orbit.request, client.request, client.Request). You keep the SDK’s auth, retries, and base URL against these raw paths. The practical server-side uses are the two machine-readable steps — fetch the SP metadata XML to ship to the IdP admin, and probe the login redirect in a smoke check (the client must not auto-follow the 302 because it targets the IdP, not Orbit). The callback remains the IdP’s own POST; there is nothing to call from your side.

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

// 1. SP metadata — hand the XML to the IdP admin (Okta/Entra app setup).
const { body: metadataXml } = await orbit.request<string>(
  'GET',
  '/auth/saml/acme-inc/metadata',
)
//    Content-Type is application/xml — ship `metadataXml` verbatim.

// 2. Probe the SP-initiated login without following the IdP-hop redirect.
const login = await orbit.request<never>('GET', '/auth/saml/acme-inc/login?redirect=/settings/team', {
  followRedirect: false, // don't chase the 302 to the IdP — we only want the Location
})
// login.status === 302, login.headers.location === the IdP SSO URL (AuthnRequest signed in).
// The ACS callback is the IdP's POST — nothing to invoke from the SDK.

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# 1. SP metadata — hand the XML to the IdP admin.
metadata = client.request("GET", "/auth/saml/acme-inc/metadata")
print(metadata["body"])          # the SP XML — ship verbatim to Okta/Entra

# 2. Probe the login redirect without following the IdP hop.
login = client.request(
    "GET",
    "/auth/saml/acme-inc/login",
    params={"redirect": "/settings/team"},
    follow_redirect=False,       # don't chase the 302 to the IdP — we want the Location
)
print(login["status"], login["headers"]["location"])   # 302, IdP SSO URL
# The ACS callback is the IdP's POST — nothing to invoke from the SDK.

// The Go SDK has no typed SAML helper — reach the routes through the
// client.Request escape hatch (raw envelope out).
var metadata map[string]any
err := client.Request(
    context.Background(),
    "GET",
    "/auth/saml/acme-inc/metadata",
    nil, nil, &metadata, "",
)
if err != nil {
    panic(err)
}
fmt.Println(metadata["body"])    // the SP XML — ship verbatim to the IdP admin

// Probe the login redirect without following the IdP hop — treat the
// returned 302 + Location as the success signal.
var none map[string]any
err = client.Request(
    context.Background(),
    "GET",
    "/auth/saml/acme-inc/login",
    map[string]string{"redirect": "/settings/team"},
    nil, &none, "",
)
// The ACS callback is the IdP's POST — nothing to invoke from the SDK.

Everything else in the round-trip (the browser hop to the IdP, the IdP’s signed ACS POST, the Clerk ticket swap) happens between the user’s browser and the IdP — the SDK can fetch metadata and probe the redirect, but it cannot stand in for the browser ceremony.

Error shapes

Failures land in the standard { "error": …, "meta": { "request_id", "timestamp" } } envelope — meta.request_id is the one handle support needs. The request ids pinned below (req_auth_saml_login, req_auth_saml_logout, req_auth_saml_callback, req_auth_saml_metadata) are worked examples of that handle, one per operation. The envelope’s error.code is the machine-readable discriminator; the callback rejections also carry a details.reason for the exact check that failed. Plan for these on the round-trip:

Status	`error.code`	`details.reason`	When it fires	Recovery
422	`ERR_BAD_RELAY_STATE`	—	RelayState missing/unsigned/corrupt on `callback`, or a malformed `orgSlug`/`nameId` on the query-string ceremonies	Re-start `GET …/login` so a fresh signed RelayState is minted; never re-send a stale one
422	`AUTH_METADATA_MISMATCH`	—	SP metadata the IdP imported doesn’t match the tenant config (entity ID, ACS URL, or x509 cert drift)	Re-download `GET …/metadata` and re-import it into the IdP app; fix the tenant SAML config
409	`CHALLENGE_TERMINAL`	—	The one-shot SSO ceremony already consumed its pending state (callback replays a used ticket)	Challenges are single-use — start a fresh `GET …/login`
401	`UNAUTHORIZED`	—	XML-DSig signature on the SAMLResponse didn’t verify against the stored IdP cert	Re-import the current IdP signing cert into the tenant config; retry the login
404	`NOT_FOUND`	`not_configured`	No SAML configuration exists for that `{orgSlug}`	Create the tenant’s SAML config, then retry the round-trip
403	`FEATURE_DISABLED`	`disabled`	SAML exists for the org but is turned off	Enable SAML on the tenant config, then retry
401	`VALIDATION_ERROR`	`conditions_not_yet_valid`, `conditions_expired`, `audience_mismatch`, `subject_confirmation_invalid`	Assertion window/audience/bearer check failed on the ACS	Fix the IdP clock skew and the Audience/Recipient it emits; retry
400	`VALIDATION_ERROR`	`audience_restriction_missing`, `conditions_missing`, `replay_ids_missing`, `subject_confirmation_missing`	Assertion is missing a mandatory element for this verifier	Have the IdP emit Conditions/AudienceRestriction/SubjectConfirmationData; retry
503	`SERVICE_UNAVAILABLE`	—	A dependency (replay-guard store, user provisioning) is briefly unavailable	Retry with backoff; escalate to support with `meta.request_id` if it persists

ERR_BAD_RELAY_STATE, AUTH_METADATA_MISMATCH, and CHALLENGE_TERMINAL are the three rejection classes the onboarding round-trip hits most — RelayState forgery/staleness on the ACS POST, IdP-side metadata drift, and a second submit of a single-use ceremony. All three recover the same way: never retry the same payload, restart GET …/login.

API Reference

All Endpoints

The SAML SSO round-trip