Skip to main content
Validate an authenticated session and run a credential fallback when the profile is not signed in.

​
librettoAuthenticate()

librettoAuthenticate is the runtime helper for workflows that combine an auth profile with a scripted login fallback. 
async function librettoAuthenticate(
  ctx: LibrettoWorkflowContext,
  options: LibrettoAuthenticateOptions,
): Promise<{ usedProfile: boolean }>;

​
Options

​
validate
(ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean
required
Checks whether the current browser page is signed in. Return true only when the workflow can safely continue.
​
fallback
(ctx: LibrettoWorkflowContext, credentials: Record<string, string>) => Promise<void> | void
required
Performs the login flow when validate returns false.
​
credentials
Record<string, unknown>
Credential values to pass to the fallback. In workflows, pass input.credentials from declared workflow credentials.
​
envPrefix
string
Optional environment variable prefix used only when credentials is omitted. Workflow code should normally pass input.credentials instead.

​
Return value

​
usedProfile
boolean
true when the initial validation passed, meaning the saved profile was already signed in. false when Libretto ran the fallback login.

​
Example

import { librettoAuthenticate, workflow } from "libretto";

export default workflow("portalReport", {
  credentials: ["username", "password"],
  authProfile: {
    name: "portal",
    refresh: true,
  },
  async handler(ctx, input) {
    const { page } = ctx;

    await page.goto("https://portal.example.com");

    await librettoAuthenticate(ctx, {
      credentials: input.credentials,
      validate: async ({ page }) =>
        await page
          .getByRole("button", { name: /account|sign out/i })
          .isVisible()
          .catch(() => false),
      fallback: async ({ page }, credentials) => {
        await page.goto("https://portal.example.com/login");
        await page.getByLabel("Email").fill(credentials.username);
        await page.getByLabel("Password").fill(credentials.password);
        await page.getByRole("button", { name: /log in/i }).click();
      },
    });

    // Continue with authenticated workflow steps.
  },
});
After fallback runs, librettoAuthenticate calls validate again. If validation still fails, it throws an error instead of letting the workflow continue in a logged-out state.
Pair librettoAuthenticate with authProfile: { name, refresh: true } when successful fallback login should update the profile for future runs.