> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Security

> Protecting forms with access controls and authentication

Forms can be protected with various security methods to ensure only the intended recipient can access them. Choosing the right security level balances protection with user convenience.

## Security Methods

Penbox offers multiple ways to secure form access:

<CardGroup cols={2}>
  <Card title="OTP Email" icon="envelope">
    One-time password sent via email

    **Security Level:** Medium to High
  </Card>

  <Card title="OTP SMS" icon="mobile">
    One-time password sent via SMS

    **Security Level:** High
  </Card>

  <Card title="Password" icon="key">
    Username and password protection

    **Security Level:** Medium
  </Card>

  <Card title="Auto Access" icon="door-open">
    Direct access via link

    **Security Level:** Low
  </Card>
</CardGroup>

## OTP Email Security

**One-Time Password via Email** requires the contact to verify their email address before accessing the form.

### How It Works

1. Contact clicks the form link
2. System prompts for email verification
3. One-time code is sent to their email
4. Contact enters the code
5. Form becomes accessible
6. Code expires after use or timeout (typically 10 minutes)

### Configuration

```json theme={null}
{
  "access_security": {
    "otp": {
      "email": {
        "enabled": true,
        "default": true,
        "mandatory": true,
        "template": "otp-email"
      }
    }
  }
}
```

**Properties:**

* `enabled`: Make this option available
* `default`: Use by default when creating forms
* `mandatory`: Must be used (can't be disabled for individual forms)
* `template`: Email template to use for sending OTP

### When to Use

<AccordionGroup>
  <Accordion title="✅ Good For">
    * Moderate security needs
    * Email verification required
    * Professional/business contexts
    * When you already have email addresses
    * Documents and data collection
  </Accordion>

  <Accordion title="❌ Not Ideal For">
    * Highest security requirements
    * When contacts may not have email access
    * Time-sensitive forms (email delays)
    * Very short forms (friction may reduce completion)
  </Accordion>
</AccordionGroup>

## OTP SMS Security

**One-Time Password via SMS** requires the contact to verify their phone number before accessing the form.

### How It Works

1. Contact clicks the form link
2. System prompts for phone verification
3. One-time code is sent via SMS
4. Contact enters the code
5. Form becomes accessible
6. Code expires after use or timeout

### Configuration

```json theme={null}
{
  "access_security": {
    "otp": {
      "sms": {
        "enabled": true,
        "default": false,
        "mandatory": false,
        "text": "Your verification code is: {code}. Valid for 10 minutes."
      }
    }
  }
}
```

**Properties:**

* `enabled`: Make this option available
* `default`: Use by default
* `mandatory`: Must be used
* `text`: SMS message template (must include `{code}`)

<Note>
  SMS messages must include the `{code}` placeholder where the actual code will be inserted.
</Note>

### When to Use

<AccordionGroup>
  <Accordion title="✅ Good For">
    * High security requirements
    * Phone number verification needed
    * Financial or sensitive information
    * When email is unreliable
    * Identity verification
  </Accordion>

  <Accordion title="❌ Not Ideal For">
    * Contacts without mobile phones
    * International users (SMS costs)
    * Areas with poor mobile coverage
    * Budget-sensitive situations (SMS costs money)
  </Accordion>
</AccordionGroup>

## Password Security

**Password Protection** requires a username and password to access the form.

### How It Works

1. Contact clicks the form link
2. System prompts for username and password
3. Contact enters credentials
4. Form becomes accessible
5. Credentials can be reused (no expiration)

### Configuration

```json theme={null}
{
  "access_security": {
    "password": {
      "enabled": true,
      "default": false,
      "mandatory": false,
      "length": 8,
      "lower": 1,
      "upper": 1,
      "numeric": 1,
      "alpha": 2,
      "login": {
        "username": "client",
        "password": "SecurePass123"
      }
    }
  }
}
```

**Properties:**

* `enabled`: Make this option available
* `default`: Use by default
* `mandatory`: Must be used
* `length`: Minimum password length
* `lower`: Minimum lowercase characters
* `upper`: Minimum uppercase characters
* `numeric`: Minimum numeric characters
* `alpha`: Minimum alphabetic characters
* `login`: Default username/password (optional)

### Password Requirements

You can enforce password complexity:

| Requirement | Description                   | Example      |
| ----------- | ----------------------------- | ------------ |
| **length**  | Minimum total characters      | 8            |
| **lower**   | Minimum lowercase letters     | 1 (a-z)      |
| **upper**   | Minimum uppercase letters     | 1 (A-Z)      |
| **numeric** | Minimum numbers               | 1 (0-9)      |
| **alpha**   | Minimum alphabetic characters | 2 (a-z, A-Z) |

### When to Use

<AccordionGroup>
  <Accordion title="✅ Good For">
    * Shared access (multiple people, same credentials)
    * Internal team forms
    * Reusable access
    * Partner portals
    * When you control credential distribution
  </Accordion>

  <Accordion title="❌ Not Ideal For">
    * Individual verification
    * One-time use
    * High security (passwords can be shared)
    * Forgot password support needed
  </Accordion>
</AccordionGroup>

## Auto Access

**Automatic Access** provides direct access to the form without additional authentication.

### How It Works

1. Contact clicks the form link
2. Form opens immediately
3. No additional verification

### Configuration

```json theme={null}
{
  "access_security": {
    // No security configured = auto access
  }
}
```

### When to Use

<AccordionGroup>
  <Accordion title="✅ Good For">
    * Public surveys
    * Feedback forms
    * Low-sensitivity data
    * Maximum convenience
    * High completion rates needed
    * General inquiries
  </Accordion>

  <Accordion title="❌ Not Ideal For">
    * Personal information
    * Financial data
    * Legal documents
    * Compliance requirements
    * Verification needed
  </Accordion>
</AccordionGroup>

<Warning>
  **Security Risk**: Anyone with the link can access the form. Only use auto-access for non-sensitive information.
</Warning>

## Combining Security Methods

You can enable multiple security methods and require specific combinations.

### Multiple Options (Choose One)

Allow contacts to choose their preferred verification method:

```json theme={null}
{
  "access_security": {
    "otp": {
      "email": { "enabled": true, "default": true },
      "sms": { "enabled": true, "default": false }
    },
    "password": { "enabled": true, "default": false }
  }
}
```

**Contact experience:**

* Sees options: "Verify by Email", "Verify by SMS", "Use Password"
* Chooses preferred method
* Completes that verification

### Multiple Requirements (All Required)

Require multiple authentication factors:

```json theme={null}
{
  "access_security": {
    "otp": {
      "email": { "enabled": true, "mandatory": true }
    },
    "password": { "enabled": true, "mandatory": true }
  }
}
```

**Contact experience:**

* Must enter password first
* Then must verify email with OTP
* Both required to access form

<Tip>
  **Multi-factor authentication** (like password + OTP) provides the highest security for sensitive forms.
</Tip>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Match security to sensitivity">
    Choose security level based on data sensitivity:

    * **High**: Financial, health, legal → OTP SMS + Password
    * **Medium**: Personal info, documents → OTP Email
    * **Low**: Surveys, feedback → Auto Access or Password
  </Accordion>

  <Accordion title="Consider user experience">
    More security = more friction = lower completion rates

    Balance security needs with completion goals. Don't use high security for low-risk forms.
  </Accordion>

  <Accordion title="Test all security methods">
    Before sending forms to contacts, test each security method to ensure it works smoothly and emails/SMS are delivered.
  </Accordion>

  <Accordion title="Communicate security to contacts">
    In invitation emails, explain why you're using security measures. This builds trust and reduces confusion.
  </Accordion>

  <Accordion title="Monitor failed access attempts">
    Track failed verification attempts. Multiple failures may indicate contact issues or security concerns.
  </Accordion>

  <Accordion title="Have fallback options">
    If using SMS, have an email backup. Some contacts may not receive SMS or prefer email verification.
  </Accordion>

  <Accordion title="Update credentials regularly">
    For password-protected forms with shared credentials, update passwords regularly and track who has access.
  </Accordion>
</AccordionGroup>

## Security Configurations by Use Case

### Financial Information

```json theme={null}
{
  "access_security": {
    "otp": {
      "email": { "enabled": true, "mandatory": true },
      "sms": { "enabled": true, "mandatory": true }
    }
  }
}
```

**Why:** Multi-factor authentication for high-value data

### Standard Document Collection

```json theme={null}
{
  "access_security": {
    "otp": {
      "email": { "enabled": true, "default": true, "mandatory": true }
    }
  }
}
```

**Why:** Email verification ensures correct recipient

### Partner Portal

```json theme={null}
{
  "access_security": {
    "password": {
      "enabled": true,
      "mandatory": true,
      "login": { "username": "partner", "password": "SecurePass123" }
    }
  }
}
```

**Why:** Shared credentials for partner access

### Public Feedback Form

```json theme={null}
{
  "access_security": {}
}
```

**Why:** No barriers to completion for low-risk data

## Form Expiration

In addition to access security, forms can have expiration dates:

```json theme={null}
{
  "expires_at": "2024-12-31T23:59:59Z"
}
```

**When a form expires:**

* The form link shows an expiration message
* Contact cannot submit the form
* Helps maintain data freshness
* Creates urgency for completion

**Use expiration for:**

* Time-sensitive offers
* Compliance deadlines
* Event registrations
* Limited-time data requests

## Custom Domains

Forms can be accessed through custom domains for improved trust:

* Default: `forms.penbox.io/abc123`
* Custom: `forms.yourcompany.com/abc123`

**Benefits:**

* Increased trust and brand recognition
* Can be whitelisted in corporate networks
* Matches your email domain
* Professional appearance

## Next Steps

<CardGroup cols={2}>
  <Card title="Form Presets" icon="sliders" href="/forms/form-presets">
    Configure security in form presets
  </Card>

  <Card title="Form Templates" icon="pen-ruler" href="/forms/form-templates">
    Build secure form templates
  </Card>

  <Card title="Forms Introduction" icon="circle-info" href="/forms/introduction">
    Back to Forms overview
  </Card>

  <Card title="Form Notifications" icon="bell" href="/forms/notifications">
    Set up form communications
  </Card>
</CardGroup>