Begin SSO (browser redirect, documentation)

Overview

Kicks off the external JumpCloud OIDC sign-in by issuing a stateful Socialite 302 redirect to JumpCloud's authorize endpoint (session middleware round-trips the OIDC state). The redirect requests scopes openid, profile, email. This is a top-level browser navigation (not an XHR/fetch call). After the user authenticates, JumpCloud bounces back to GET /auth/sso/jumpcloud/callback. That callback issues a one-time SsoExchangeCode and redirects the SPA to the frontend callback URL with ?code=<raw> (or ?error=<reason>). The SPA then redeems that code at GET /auth/sso/exchange for a Passport access token.

Prerequisites

• No authentication — this endpoint is public.

Base URL

Endpoint

GET /api/v1/auth/sso/jumpcloud/redirect

Authentication

• No bearer token required.
• Public/unauthenticated — this endpoint does not require authentication.
• It runs under the web route guard group so Socialite can store and round-trip the OIDC state CSRF parameter in the session.
• JumpCloud requires a non-empty state ≥ 8 chars.
• No role scoping happens at this step — it only redirects to the IdP.
• The endpoint enforces role eligibility later in the callback.
• Super-admins (the account's bundle_id 0/null) are hard-blocked.
• Only customer-tier users (bundle_id ≥ 1 — agency/Partner, account, store) with jumpcloud in their auth_methods and an associated company are allowed through.

Rate limit

• 10 requests/min per IP.

Request

• No path params, query params, or body.

Response

• Location (header) — JumpCloud OIDC authorize endpoint URL including client_id, redirect_uri, response_type=code, scope=openid profile email, and a generated state.

Success example

HTTP/1.1 302 Found
Location: https://oauth.id.jumpcloud.com/oauth2/auth?client_id=<client_id>&redirect_uri=<callback>&scope=openid+profile+email&response_type=code&state=<random>

Note: this endpoint is for documentation only. It is meant to be opened directly in a browser, not invoked from the SPA's HTTP layer, since the response is a redirect rather than JSON.

302 Redirect to JumpCloud · 302

(empty body)

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/auth/sso/jumpcloud/redirect" \
  --header 'Accept: application/json'