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

# Authentication

> Configure authentication credentials for testing protected endpoints

## Overview

Many applications have functionality behind authentication - admin panels, user dashboards, API endpoints requiring authorization, and more. To test these protected areas, Pensar needs authentication credentials. This guide explains how to provide credentials so the AI agent can authenticate and test your entire application surface.

> **Info**
>
> Authentication credentials are provided when [adding domains](/console/domains/adding-domains) to your workspace. They're stored
> securely and only used during penetration testing.

## Why Provide Authentication?

Testing authenticated areas of your application is critical for comprehensive security coverage:

#### Authorization Testing

Test for broken access control, privilege escalation, and improper
authorization checks.

#### Complete Coverage

Access endpoints and functionality that require authentication, dramatically
increasing test coverage.

#### IDOR Detection

Discover Insecure Direct Object Reference (IDOR) vulnerabilities where users
can access other users' data.

#### Session Security

Test session management, token handling, and authentication mechanism
security.

## Supported Authentication Types

Pensar supports multiple authentication mechanisms:

#### Username & Password

The most common authentication method for web applications.

### What to Provide

* **Username or Email**: The credential used to log in
* **Password**: The corresponding password
* **Role**: Description of the user role (e.g., "admin", "standard user", "manager")
* **Context**: Detailed instructions on how to use these credentials for authentication

### Example Configuration

```text
Username: testuser@example.com
Password: SecureTestPassword123!
Login URL: https://app.example.com/login
Context: After login, the user is redirected to /dashboard
```

> **Warning**
>
> Create a dedicated test account for Pensar rather than using production user
> credentials. This account should have representative permissions but not
> access to sensitive production data.

#### Bearer Token

For API testing or applications using token-based authentication.

### What to Provide

* **Token**: The JWT, API key, or other token value
* **Role**: Description of what this token can access (e.g., "admin API access", "read-only")
* **Context**: Detailed instructions on how to use this token, including header format and any special requirements

### Example Configuration

```text
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Header: Authorization
Format: Bearer {token}
Context: This token has admin-level access and expires in 30 days
```

### Generating Test Tokens

#### Create Test User

Create a test user account with appropriate permissions in your application.

#### Generate Token

Use your application's token generation mechanism to create a long-lived test token.

#### Verify Token

Test the token manually to ensure it works and has the expected permissions.

#### Provide to Pensar

Add the token when configuring domain authentication in the Console.

#### Custom Headers

For proprietary authentication mechanisms that use custom HTTP headers.

### What to Provide

* **Custom Headers**: Key-value pairs of custom headers required for authentication
* **Role**: Description of what access level these credentials provide
* **Context**: Comprehensive explanation of the auth system and how to use the headers

### Example Configuration

```text
Custom Headers:
X-API-Key: sk_test_abc123xyz789
X-Client-ID: client_12345
X-Session-Token: session_xyz789abc

Role: Admin API Access
Context: These headers must be included in all API requests. The X-Session-Token expires after 6 hours. Include all three headers for full admin access to /api/* endpoints.
```

### Common Use Cases

* API key authentication with custom header names
* Multi-header authentication systems
* Session token authentication
* Legacy systems with proprietary auth mechanisms

> **Info**
>
> Provide all custom headers required for authentication. The AI agent will include these headers in all requests during testing.

## Adding Authentication Credentials

Authentication is configured when adding domains to your workspace:

#### Navigate to Add Domain

When [adding a domain](/console/domains/adding-domains), you'll see an
authentication section.

#### Choose Authentication Type

Select the authentication method your application uses (username/password,
bearer token, etc.).

#### Provide Credentials

Enter the authentication credentials and any required context.

#### Add Context

Provide detailed context about how to use the credentials: - Login process
steps - Special requirements or behaviors - Expected authentication flow -
Session duration and handling

#### Save Configuration

Save the domain configuration. Credentials are encrypted and stored
securely.

> **Success**
>
> The AI agent uses your provided context to understand how to authenticate. The
> more detailed your context, the better the agent can navigate authentication
> flows.

## TOTP seeds

Use a TOTP seed when a test account signs in with an authenticator app that
generates a rotating code. This is different from an SMS-delivered code: see
[Mobile OTP](#totp-and-mobile-otp) below for that flow.

> **Info**
>
> TOTP is an additional secret on a **Username & Password** credential, not a
> separate credential type. Pensar supports standard six-digit, 30-second,
> SHA-1 TOTP codes.

### Configure a test credential

#### Use a dedicated test account

Create or use a test account with representative permissions. Do not use an
employee account or an account that can access real customer data.

#### Obtain the authenticator setup key

During MFA enrollment, the application provides a QR code and often a
manual setup key. Copy the base32 setup key. If the account is already
enrolled and the application will not reveal the key, reset and re-enroll
MFA for the dedicated test account.

#### Add the secret to the credential

In **Settings → Credentials**, add or edit the Username & Password
credential for that account. Under **Additional Secrets**, add a secret
named `TOTP_SEED` and paste the base32 setup key as its value.

#### Save and retest

Save the credential and select **Retest**. Once the credential test
succeeds, dispatch a new pentest or restart only the endpoints previously
blocked by MFA.

### Use the setup key, not a current code

The enrollment QR code represents a value like
`otpauth://totp/...?...&secret=BASE32_SETUP_KEY`. Enter only the base32 value
from the `secret` parameter.

Do not enter:

* A current six-digit code from an authenticator app — it expires and cannot
  generate future codes.
* The full `otpauth://` URI or a QR-code image.
* A recovery code, passkey, push-approval token, or SMS code.

> **Warning**
>
> The TOTP seed is as sensitive as a password. Do not paste it into
> credential context, agent instructions, chat, tickets, scripts, logs, or
> third-party QR-code decoders.

### How Pensar uses the seed

Pensar stores the seed as encrypted credential data. The agent is told that a
TOTP secret exists, but the value is injected only into the isolated test run
when it is needed and is redacted from agent output.

Immediately before an authenticator prompt, Apex computes the current
six-digit code from the seed and the current time. Codes rotate every 30
seconds. If a submission crosses a time-window boundary, the agent generates a
fresh code and retries once.

Each account needs its own seed. Add `TOTP_SEED` separately to every credential
whose account has a different authenticator enrollment. Edited credentials apply
to newly dispatched runs; a sandbox that is already running keeps the
credential snapshot with which it started.

### TOTP and Mobile OTP

#### Authenticator TOTP

The application asks for a code from an authenticator app such as 1Password,
Google Authenticator, or Authy. Add the account's base32 setup key as the
`TOTP_SEED` additional secret.

#### Mobile OTP

The application sends a code by SMS. Enable **Mobile OTP** on the
Username & Password credential. Pensar reserves a platform-managed
receiving number for the test run, waits for the code, and submits it.

Mobile OTP does not provide authenticator-app codes, and a TOTP seed does
not receive SMS messages.

### Troubleshoot TOTP authentication

#### The setup key is unavailable

Reset and re-enroll MFA for the dedicated test account. A displayed
six-digit code cannot be reversed to recover the original seed.

#### Fresh codes are rejected

Confirm the seed belongs to the exact test account and that the provider
uses six-digit, 30-second, SHA-1 TOTP. Re-enroll the account if the seed is
stale or the provider uses a different algorithm, code length, or rotation
interval.

#### A pentest still reports an MFA barrier

Retest the credential first. Then start a new run or restart the affected
endpoints: active sandboxes do not reload edited credentials.

#### The provider asks for push approval, a passkey, or WebAuthn

These verification methods are not TOTP. Configure an alternative
dedicated test-account flow, such as standard TOTP or SMS Mobile OTP, for
autonomous testing.

## Context Examples

Providing good context is crucial for successful authentication. Here are examples:

#### Simple Login Form

```text
Navigate to https://app.example.com/login
Enter the username in the "Email" field
Enter the password in the "Password" field
Click the "Sign In" button
You'll be redirected to /dashboard upon successful login
The session cookie is automatically set and valid for 24 hours
```

#### Multi-Step Authentication

**`Step 1: Navigate to https://app.example.com/login Step 2: Enter`**

````text Step 1: Navigate to https://app.example.com/login Step 2: Enter
username and click "Continue" Step 3: Enter password on the next screen Step
4: A 2FA code is sent to email (use code: 123456 for test account) Step 5:
Enter 2FA code and click "Verify" Step 6: You'll be logged in and redirected
to /home Session lasts 12 hours ```
</Accordion>

<Accordion title="API Authentication" icon="code">
```text All API requests require authentication via Bearer token Add the token
to the Authorization header: "Authorization: Bearer {token}" The token
provides admin-level access to all API endpoints Token is valid for 30 days No
additional authentication steps needed ```
</Accordion>

<Accordion title="Role-Based Access" icon="users">
  ```text
  This account has "manager" role with access to:
  - All /api/projects/* endpoints
  - Admin panel at /admin (limited access)
  - User management at /admin/users

  This account CANNOT access:
  - /admin/system (requires admin role)
  - /api/billing/* (requires owner role)

  Login at https://app.example.com/login with provided credentials
  Session persists across browser sessions via "Remember me" cookie
````

## Security Best Practices

#### Use Test Accounts

**Always** create dedicated test accounts for Pensar:

* Don't use production user accounts
* Don't use accounts with access to real customer data
* Create accounts specifically for security testing
* Use realistic permissions but isolate from production data

> **Warning**
>
> Never provide credentials for accounts with access to sensitive production data or systems.

#### Limit Permissions

Test accounts should have representative permissions but be limited:

* Grant enough access to test key functionality
* Avoid overly privileged accounts (e.g., super admin)
* Use role-based access control to limit scope
* Test multiple permission levels by providing multiple accounts

Consider providing multiple test accounts with different roles:

* Regular user account
* Manager/power user account
* Limited admin account

#### Use Staging Environments

When possible, test against staging rather than production:

* Staging credentials can be less restrictive
* No risk to production data or systems
* More flexibility for destructive testing
* Easier to reset state between tests

#### Rotate Test Credentials

Regularly rotate and update test credentials:

* Change test account passwords periodically
* Regenerate API tokens regularly
* Remove unused test accounts
* Monitor test account activity

#### Secure Credential Storage

Pensar handles credentials securely:

* Credentials are encrypted at rest
* Transmitted only over secure connections
* Only used during active penetration tests
* Not logged or exposed in reports
* Accessible only to your workspace team

You can update or remove credentials anytime in the Console.

## Testing Multiple User Roles

To comprehensively test authorization, provide credentials for multiple user roles:

#### Identify Roles

List all user roles in your application:

* Public/unauthenticated user
* Regular authenticated user
* Premium/paid user
* Manager or team lead
* Administrator
* Super admin/owner

#### Create Test Accounts

Create a test account for each significant role with different permissions.

#### Add to Pensar

When adding a domain, provide credentials for each role in the context:

```text
Regular User:
- Username: regular@test.com
- Password: RegularUser123!
- Access: Basic user features only

Manager User:
- Username: manager@test.com
- Password: Manager123!
- Access: Team management and reporting

Admin User:
- Username: admin@test.com
- Password: Admin123!
- Access: Full admin panel (except system config)
```

#### Test Authorization

Pensar will test with each credential set to find authorization vulnerabilities like:

* Privilege escalation
* Horizontal authorization bypass (accessing other users' data)
* Vertical authorization bypass (accessing admin functions)

## Troubleshooting Authentication

If authentication isn't working during testing:

#### Verify Credentials Manually

Test the credentials yourself:

* Log in manually using the provided credentials
* Ensure the credentials still work
* Verify the account hasn't been locked or disabled
* Check that the credentials have expected permissions

#### Check Context Accuracy

Review your authentication context: - Are all steps clearly explained? - Is
the login URL correct? - Are there any missing steps (e.g., CAPTCHAs, 2FA)? -
Does the flow match the current application behavior?

#### Review Test Results

Check the test logs in Pensar Console: - Look for authentication error
messages - Verify the agent is following your auth steps correctly - Check if
rate limiting is blocking login attempts - See if sessions are expiring too
quickly

#### Update Configuration

Update your authentication configuration:

* Provide more detailed context
* Use a different authentication method if available
* Generate new tokens or passwords
* Add troubleshooting notes for the agent

## Example Configurations

Here are complete examples for common scenarios:

### E-Commerce Application

```text
Primary User Account:
- Email: buyer@test.com
- Password: BuyerTest123!
- Login URL: https://shop.example.com/account/login
- Context: Regular customer account with saved payment methods and order history. Can access /account/*, /orders/*, and checkout flow.

Admin Account:
- Email: shopadmin@test.com
- Password: AdminTest123!
- Login URL: https://shop.example.com/admin/login
- Context: Store administrator with access to /admin/* except /admin/system. Can manage products, view orders, and manage customers but cannot access system settings.
```

### SaaS Platform

```text
API Authentication:
- Bearer Token: sk_test_1a2b3c4d5e6f7g8h9i0j
- Header: Authorization
- Format: Bearer {token}
- Context: This token represents a test organization account with workspace admin permissions. Valid for all /api/v2/* endpoints. Token expires in 90 days.

Web Application:
- Email: orgadmin@test.com
- Password: OrgAdmin123!
- Login URL: https://app.example.com/login
- Context: Organization administrator. After login, redirected to /dashboard. Has access to all features except billing/payment (requires owner role). Session lasts 7 days with "Remember me" enabled.
```

### Custom API Authentication

```text
Authentication Type: Custom Headers
Custom Headers:
- X-API-Key: sk_live_abc123xyz789secret
- X-Client-ID: mobile_test_client
- X-Request-ID: req_test_12345

Role: Full API Access
Context:
  1. All three headers must be included in every request
  2. X-Request-ID can be any unique identifier for testing
  3. All /api/v1/* endpoints require these headers
  4. Test credentials have full API access
  5. No token expiration - these are long-lived test credentials
```

## Next Steps

#### [Adding Domains](/console/domains/adding-domains)

Learn how to add and verify domains where you'll configure authentication.

#### [Hybrid Testing](/console/features/hybrid-testing)

Learn how authentication credentials enhance Pensar's hybrid testing
methodology for maximum coverage.

#### [Getting Started](/console/getting-started)

Return to the getting started guide to continue setup.