Overview The Authentication API provides intelligent authentication capabilities that handle various login mechanisms including form-based auth, OAuth, API tokens, and complex multi-step flows. It securely manages credentials and exports session data for use in subsequent testing.
Key Features:
Automatic credential management via CredentialManager
Support for multiple auth schemes (forms, OAuth, JWT, API keys)
Browser automation for complex login flows
CSRF and anti-bot handling
Email verification support
Secure credential storage with no raw secrets in prompts
Session export (cookies, headers, tokens)
runAuthenticationAgent Authenticate against a target and persist the session for subsequent operations.
Authentication Flow:
Agent navigates to the target/login page
Detects authentication mechanism
Uses browser tools to fill forms and interact with auth flows
Handles CSRF tokens, CAPTCHAs, email verification
Validates successful authentication
Exports cookies and headers
Persists auth data to session directory
import { runAuthenticationAgent } from '@pensar/apex/api/authentication' ; // Credentials are managed automatically via session config const result = await runAuthenticationAgent ({ target: 'https://app.example.com' , model: 'claude-sonnet-4-20250514' , session: sessionInfo , // Session with authCredentials configured }); if ( result . success ) { console . log ( 'Authentication successful!' ); console . log ( `Strategy: ${ result . strategy } ` ); console . log ( `Cookies: ${ result . exportedCookies } ` ); }
Parameters input
AuthenticationAgentInput
required
Configuration for the authentication agent Show AuthenticationAgentInput properties
The target URL requiring authentication (typically the login page or base URL)
AI model identifier (e.g., "claude-sonnet-4-20250514")
Session object. When created with authCredentials in the config, a CredentialManager is automatically provisioned. The agent reads credentials via credential IDs — raw secrets never appear in prompts.
Optional hints about the authentication flow to guide the agent Show authHints properties
Expected auth scheme (e.g., "form", "oauth2", "bearer", "api-key")
Whether CSRF protection is detected
Whether browser automation is needed (for JS-heavy SPAs)
List of endpoints that require authentication (for verification)
Optional per-provider API key overrides
AbortSignal to cancel authentication mid-run
onStepFinish
StreamTextOnStepFinishCallback
Callback fired after each agent step completes
Stream event callbacks for monitoring authentication progress Show ConsumeCallbacks properties
Called for each text chunk streamed from the AI
Called when the agent invokes a tool
Called when a tool execution completes
Called when an error occurs
Response Whether authentication was successful
Human-readable summary of the authentication process
Session cookies in HTTP Cookie header format (e.g., "session=abc123; csrf=xyz456")
Additional headers required for authenticated requests (e.g., Authorization tokens) Example: { "Authorization" : "Bearer eyJhbGc..." , "X-CSRF-Token" : "abc123" }
Authentication strategy used (e.g., "form-based", "oauth2", "api-key", "session-cookies")
Details about any authentication barrier encountered during the process Show AuthBarrier properties
Type of barrier (e.g., "captcha", "2fa", "email-verification")
Description of the barrier
Whether the barrier was successfully bypassed
Absolute path to the persisted auth-data.json file in the session directory
Usage Examples Basic Authentication
OAuth Authentication
With Progress Monitoring
API Key Authentication
Multi-Step Authentication
import { runAuthenticationAgent } from '@pensar/apex/api/authentication' ; import { createSession } from '@pensar/apex/session' ; // Create session with credentials const session = await createSession ({ name: 'Auth Test' , targets: [ 'https://app.example.com' ], config: { authCredentials: { username: 'testuser' , password: 'testpass' , loginUrl: 'https://app.example.com/login' , }, }, }); // Run authentication const result = await runAuthenticationAgent ({ target: 'https://app.example.com' , model: 'claude-sonnet-4-20250514' , session , }); if ( result . success ) { console . log ( 'Authenticated successfully!' ); console . log ( `Strategy: ${ result . strategy } ` ); // Use exported credentials in subsequent requests const response = await fetch ( 'https://app.example.com/api/user' , { headers: { Cookie: result . exportedCookies , ... result . exportedHeaders , }, }); }
Credential Management Automatic Credential Provisioning When you create a session with authCredentials, a CredentialManager is automatically created:
const session = await createSession ({ name: 'My Session' , targets: [ 'https://example.com' ], config: { authCredentials: { username: 'user' , password: 'pass' , loginUrl: 'https://example.com/login' , }, }, }); // session.credentialManager is now available
The CredentialManager:
Stores secrets securely in memory
Never exposes raw secrets in AI prompts
Provides credential IDs for safe reference
Resolves secrets only at tool execution time
Supported Credential Types
Username/Password : Traditional form-based authenticationAPI Keys : Bearer tokens, API keysOAuth Tokens : Access tokens, refresh tokensSession Cookies : Pre-authenticated session cookiesCustom Fields : Any additional auth fields
Authentication Strategies The agent automatically detects and handles various authentication mechanisms:
Detects username/password fields
Handles CSRF tokens
Manages session cookies
Follows redirects
OAuth 2.0
Handles authorization flow
Manages token exchange
Exports access tokens
API Key/Bearer Token
Validates API key format
Tests protected endpoints
Exports authorization headers
Session-Based
Imports existing cookies
Validates session state
Exports refreshed session
Blackbox Pentest Full pentest with automatic auth
Targeted Pentest Test authenticated endpoints
Attack Surface Map authenticated attack surface
