Auto-detection

unknown is the default, and it is not a placeholder: it is a request to work the mode out. Two mechanisms do that, at two different moments, and confusing them makes the behaviour look erratic.

Detection: the precedence

detectAuthMode(config, preLogin) decides, in this order:

Two things follow. Declaring a mode is absolute: an explicit sso, bearer, oauth or saml is never overridden by what the server announces. And OAuth wins over SAML when both are configured.

The probe: resolving unknown at sign-in

With the mode still unknown, login() runs the ambient handshake — a request to a protected endpoint that lets the server challenge it:

• It succeeds → the mode becomes sso, and the session is recorded.
• It fails → the mode becomes credentials, and a form is what your interface should render.

That fallback is announced in the logs rather than done silently, because the reason is almost always a configuration the client never received: no token for a token-authenticated server, or a provider that neither the configuration nor the pre-login response declared.

import { createAtomicClient, isExternalAuthMode } from "@sinequa/atomic";

// No authMode: the default is unknown, which means "work it out".
const client = createAtomicClient({
  app: "<your-app>",
  backendUrl: "https://<your-sinequa-server>",
});

// Reads the pre-login response and applies the precedence above.
await client.initializeConfig();
console.log("detected:", client.config.authMode?.kind);

const signedIn = await client.auth.login();

if (signedIn) {
  start();
} else if (isExternalAuthMode(client.config.authMode)) {
  // oauth and saml navigate away, so reaching here means the redirect did not
  // happen or came back empty — not a case for a password form.
  showError("Sign-in did not complete.");
} else {
  // Resolved to credentials: the form owns the sign-in from here.
  showForm();
}

function start() {}
function showForm() {}
function showError(message: string) {
  console.error(message);
}

import { ChangeDetectionStrategy, Component, computed, inject } from "@angular/core";
import { isExternalAuthMode } from "@sinequa/atomic";
import { SINEQUA } from "./sinequa";

/**
 * Renders from the mode the initializer resolved. `config` is a live view, so by
 * the time this component exists the value reflects detection.
 */
@Component({
  selector: "app-auth-gate",
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @if (signedIn()) {
      <router-outlet />
    } @else if (external()) {
      <p>Signing you in…</p>
    } @else {
      <app-sign-in />
    }
  `,
})
export class AuthGateComponent {
  private readonly client = inject(SINEQUA);

  readonly signedIn = computed(() => this.client.auth.isAuthenticated());

  /** True for sso, oauth, saml and bearer — every mode with no form to show. */
  readonly external = computed(() => isExternalAuthMode(this.client.config.authMode));
}

import { isExternalAuthMode } from "@sinequa/atomic";
import type { ReactNode } from "react";
import { sinequa } from "./sinequa";
import { SignIn } from "./SignIn";

/**
 * Renders from the mode resolved during start-up. `config` is a live view, so this
 * reads the detected value rather than the one passed at creation.
 */
export function AuthGate({ children }: { children: ReactNode }) {
  if (sinequa.auth.isAuthenticated()) return <>{children}</>;

  // True for sso, oauth, saml and bearer — every mode with no form to show.
  if (isExternalAuthMode(sinequa.config.authMode)) return <p>Signing you in…</p>;

  return <SignIn onSignedIn={() => window.location.reload()} />;
}

When a session already exists under unknown

A subtler case: login() finds a valid session, but nothing on the wire says whether it came from a form or from the host. It is resolved like this, in order:

1. A configured transport — an SPFx AadHttpClient, any injected httpAdapter — settles it as sso. Such a transport authenticates every request itself, so the session cannot have come from a form. This is a fact about the current page.
2. Otherwise, a marker in localStorage written by the last credentials sign-in settles it as credentials.
3. Otherwise, sso.

A real session found by the ambient probe also takes precedence over the marker: if the handshake succeeds, the mode is sso even when the marker says otherwise.

Pitfalls

What's next