> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/apex/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/apex/_mcp/server.

# runAuthenticationAgent

> Log in to a target with session credentials and export the resulting cookies and headers

**`Signature`**

```ts title="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`**

```ts title="Import"
import { runAuthenticationAgent } from "@pensar/apex/core/api";
```

## Parameters

**`target`** `string` — required

The application to authenticate against.

---

**`session`** `SessionInfo` — required

A session created with `config.authCredentials`. Its credential manager supplies secrets to the agent. See [sessions](/apex/sdk/reference/sessions#authentication-credentials).

---

**`model`** `AIModel` — required

Model ID. See [Models](/apex/sdk/configuration#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](/apex/sdk/reference/agent-event-bus).

---

**`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

```ts
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);
}
```