Prerequisites
The four things that must exist on the server before your first request can succeed, and how to verify each one.
This library talks to a configured Sinequa server. Nothing you write on the client can substitute for that configuration, so it is worth confirming it before debugging your own code — most first-run failures are a missing piece here, not a mistake in the application.
What you need
Prop
Type
Ask whoever administers the server for the first two. If a Sinequa interface is already deployed, both are
readable from its URL: https://search.example.com/app/my-app gives you the origin and the app name.
Verifying it, in order
Each step depends only on the ones before it, so the first failure tells you where the problem is. The last two steps continue from the client created in step 2 rather than repeating it.
The server answers, and the app exists
The pre-login endpoint needs no session, which makes it the cleanest first probe. A 200 proves the origin is
right, the app name is right, and nothing between you and the server is blocking the request.
import { createAtomicClient } from "@sinequa/atomic";
const client = createAtomicClient({
app: "<your-app>",
backendUrl: "https://<your-sinequa-server>",
});
// Resolves configuration and reads the pre-login response.
const preLogin = await client.initializeConfig();
console.log("reachable. announced providers:", preLogin.providers ?? "(none)");A failure here is a URL, an app name, or CORS — never authentication.
Signing in succeeds
login() branches on whatever the server announced. What "success" looks like depends on the mode, so read the
returned value rather than assuming an exception:
import { createAtomicClient, isExternalAuthMode } from "@sinequa/atomic";
const client = createAtomicClient({
app: "<your-app>",
backendUrl: "https://<your-sinequa-server>",
});
await client.initializeConfig();
const signedIn = await client.auth.login();
const mode = client.config.authMode;
if (signedIn) {
console.log("signed in, mode:", mode?.kind);
} else if (isExternalAuthMode(mode)) {
// oauth and saml navigate away; this line is reached only if that did not happen.
console.log("provider sign-in did not establish a session, mode:", mode?.kind);
} else {
console.log("this server expects a username and password");
}If it reports that the server expects credentials when you know it uses SSO, the server did not authenticate the request — see Windows and reverse-proxy SSO.
The session is real
login() returning true says the handshake completed. A protected endpoint says the session actually works:
const principal = await client.api.principal.get();
console.log("signed in as:", principal.name, principal.id);
console.log("administrator:", principal.isAdministrator);A 401 here, after a successful sign-in, means the session was established but is not being sent — usually a
cross-origin cookie problem. See the CORS note below.
A search returns something
The last step exercises the query web service, which is the one piece of configuration the previous steps did not touch:
const result = await client.api.query.search({
name: "<your-query>",
text: "*",
pageSize: 1,
});
console.log("total documents visible to you:", result.rowCount);
console.log("facets configured:", result.aggregations?.map((a) => a.name));rowCount: 0 with no error is a legitimate answer — the index may be empty, or this user may see nothing.
Check result.$error to tell that apart from a failed request. An error naming the web service means _query
is not the right name: list app.queries to find the real one.
Cross-origin setups
If your application is not served from the Sinequa origin — a local dev server against a remote backend, the usual case — use a development proxy: see Developing against a remote server. CORS alone is not enough, because the session is a cookie and a third-party cookie is restricted by default.
Should you configure CORS anyway, the requirements are:
- The origin of your application must be allowed by the server's CORS configuration.
- Credentials must be allowed, because the session lives in a cookie.
Access-Control-Allow-Origin: *is not sufficient with credentials; the origin must be named. - The library sends
credentials: "include"by default. Do not turn that off to "fix" a CORS error — it removes the session instead.
A development proxy changes the picture for OAuth and SAML
With a provider redirect, the identity provider returns to whichever origin the callback is registered against.
If that is the backend host while your application runs on localhost, the session cookie is set on the wrong
origin: the provider completes its part and your application still has no session. This surfaces as a
sign-in loop, guarded against — see OAuth and SAML.
Keeping the placeholders
Every example in this documentation uses https://<your-sinequa-server> and app: "<your-app>" rather than a
real deployment. Substitute your own values, or read them from the environment so the same code runs against a
development and a production server:
import { createAtomicClient } from "@sinequa/atomic";
export const sinequa = createAtomicClient({
app: process.env.SINEQUA_APP,
backendUrl: process.env.SINEQUA_URL,
});Both keys are optional: with the application served from the Sinequa origin under /app/<name>, the client
derives them from the page URL.