---
title: "Initialize authentication session"
method: POST
path: "/userAccount/initAuth"
tags: ["User Account"]
---

# Initialize authentication session

`POST /userAccount/initAuth`

Start a server-side authentication session and discover which sign-in methods are
configured for the organization. This is the first step in the multi-step login flow.

**Request body (optional)**

- You may omit the body, send an empty JSON object `{}`, or send `{ "email": "..." }`.
- `email` in the body is optional and kept for legacy reasons; omitting it does not prevent
  initialization. The web client typically calls this endpoint without a body and sends
  `email` on `/authenticate` instead.
- When provided, `email` is stored on the session for correlation with subsequent steps.

**Flow:**

1. Call this endpoint (optional JSON body as above).
2. Receive a session token in the `x-session-token` response header.
3. Send that token on subsequent `/authenticate` requests (`x-session-token` header).
4. Use `allowedMethods` and `authProviders` from the response to render the login UI.

**Session token**

- Returned as header `x-session-token`.
- Required for `/authenticate` (and related steps) until it expires.

**Multi-factor authentication**

If the organization has MFA, complete multiple authentication steps; each step may
return the next step's allowed methods.

## Request body

- InitAuthRequest — Optional JSON body for `/userAccount/initAuth`. Valid shapes include: omitting the body entirely, sending `{}` (empty object), or `{ "email": "<address>" }`. Neither the body nor `email` is required. When `email` is omitted or empty, the session is still created and `allowedMethods` / `authProviders` are returned as usual; clients typically supply `email` later on `/userAccount/authenticate`. The `email` property remains supported mainly for legacy clients and backward compatibility.
  - `email` string, email — Optional; retained for legacy reasons. When set, stored on the auth session for correlation with later `/authenticate` calls (RFC 5321 compliant address).

## Response `200`

Authentication session initialized successfully

- InitAuthResponse — Response containing available authentication methods and session info
  - `currentStep` integer, required — Current authentication step (0-indexed). Always 0 for initial response.
  - `allowedMethods` string[], required — List of allowed authentication methods for the current step
  - `message` string, required — Response message
  - `authProviders` AuthProviders, required — Configuration for external authentication providers (returned when those methods are allowed)
    - `google` AuthProviderGooglePublicConfig — Public Google OAuth settings returned to clients
      - `clientId` string — Google OAuth client ID
      - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Google
    - `microsoft` AuthProviderMicrosoftPublicConfig — Public Microsoft OAuth settings returned to clients
      - `tenantId` string — Microsoft tenant ID
      - `clientId` string — Microsoft OAuth client ID
      - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Microsoft
    - `azuread` AuthProviderAzureAdPublicConfig — Public Azure AD OAuth settings returned to clients
      - `tenantId` string — Azure AD tenant ID
      - `clientId` string — Azure AD client ID
      - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Azure AD
    - `oauth` AuthProviderOAuthPublicConfig — Public generic OAuth provider settings returned to clients
      - `providerName` string, required — Custom OAuth provider display name
      - `clientId` string, required — OAuth client ID
      - `tokenEndpoint` string, required — OAuth token endpoint URL
      - `authorizationUrl` string, required — OAuth authorization URL
      - `clientSecret` string — Client secret (omitted when stripped for public responses)
      - `userInfoEndpoint` string — UserInfo endpoint URL
      - `scope` string — Default OAuth scopes
      - `enableJit` boolean — Whether just-in-time user provisioning is enabled for this provider
    - `saml` object — Present when SAML SSO is an allowed method; may be an empty object
  - `jitEnabled` boolean, required — True when at least one allowed external provider has JIT provisioning enabled

## Other responses

- `400` — Invalid request (e.g. malformed `email` when that property is sent)
- `500` — Internal server error

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)