runAuthenticationAgent

Signature

function runAuthenticationAgent(
  input: AuthenticationAgentInput,
): Promise<AuthenticationResult>;

Drives a target’s login flow with an AI agent and returns reusable authentication material. The agent uses a real browser and can work through form logins, OAuth, SPAs, CSRF tokens, and email or SMS one-time codes (if inboxes are configured). Use the exported cookies and headers to authenticate other tools or pentest runs.

The model never sees your raw secrets. Credentials go into the session’s authCredentials, and tools resolve them at execution time.

Import

import { runAuthenticationAgent } from "@pensar/apex/core/api";

Parameters

target

stringRequired

The application to authenticate against.

session

SessionInfoRequired

A session created with config.authCredentials. Its credential manager supplies secrets to the agent. See sessions.

model

AIModelRequired

Model ID. See Models.

authConfig

AIAuthConfig

AI provider credentials.

authHints

{ authScheme?: string; csrfRequired?: boolean; browserRequired?: boolean; protectedEndpoints?: string[] }

Optional hints about the login flow. protectedEndpoints gives the agent URLs to verify the session against.

context

string

Free-form context about the application.

eventBus

AgentEventBus

Streaming events. See AgentEventBus.

abortSignal

AbortSignal

Cancels the run.

Returns

Promise<AuthenticationResult>

success

boolean

Whether the agent authenticated.

summary

string

What the agent did and why it succeeded or failed.

strategy

string

How the agent authenticated: browser, form_post, json_post, basic_auth, or bearer. unknown if it couldn’t tell.

exportedCookies

string

Session cookies, formatted for a Cookie header.

exportedHeaders

Record<string, string>

Headers to send on authenticated requests, such as Authorization.

authBarrier

AuthBarrier | undefined

Set when the agent hit a barrier, such as a CAPTCHA or MFA it couldn’t complete.

authDataPath

string

Path to the auth data the agent saved in the session’s auth/ directory.

Example

import { buildAuthConfig } from "@pensar/apex/core/ai";
import { runAuthenticationAgent } from "@pensar/apex/core/api";
import { config } from "@pensar/apex/core/config";
import { sessions } from "@pensar/apex/core/session";
const target = "https://staging.example.com";
const session = await sessions.create({
  name: "Auth check",
  targets: [target],
  config: {
    authCredentials: {
      username: "admin@example.com",
      password: process.env.STAGING_ADMIN_PASSWORD,
      loginUrl: `${target}/login`,
    },
  },
});
const auth = await runAuthenticationAgent({
  target,
  session,
  model: "claude-opus-4-6",
  authConfig: buildAuthConfig(await config.get()),
  authHints: { protectedEndpoints: [`${target}/api/me`] },
});
if (auth.success) {
  const res = await fetch(`${target}/api/me`, {
    headers: { ...auth.exportedHeaders, Cookie: auth.exportedCookies },
  });
  console.log(res.status);
} else {
  console.error(auth.summary, auth.authBarrier);
}