API Multi-User Testing¶

The configuration patterns for API Testing are structurally similar to WebApp Testing examples, with the following modifications:

1. Authentication Type: Replace browser_agent with appropriate API authentication methods (http_basic, bearer_token, cookie, header, or manual)
2. WebApp Testing Block: Remove the frontend_dast configuration block

API Testing Example (Tenant Isolation Pattern)¶

Scenario: Validation that users in different tenants cannot access each other's data, despite having equivalent permission levels.

Use Case: This pattern tests Tenant Isolation (Symmetric Permissions) for API endpoints where users with the same role in different tenants should remain strictly isolated from each other's data.

Configuration:

authentication:
  presets:
    - type: bearer_token
      users:
        - username: user@tenant-a.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          main_user: true
        - username: user@tenant-b.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

security_tests:
  tenant_isolation:
    skip: false
    main_user: user@tenant-a.com

This configuration validates tenant isolation for API endpoints by replaying requests with different bearer tokens and comparing response fingerprints.

API Testing Example (Privilege Escalation Pattern)¶

Scenario: Validation that a lower-privilege user cannot access features or data restricted to higher-privilege users within the same tenant.

Use Case: This pattern tests Privilege Escalation (Asymmetric Permissions) for API endpoints where users with different roles (e.g., admin vs member) within the same organization should have different access levels.

Configuration:

authentication:
  presets:
    - type: bearer_token
      users:
        - username: admin@company.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          main_user: true
        - username: member@company.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

security_tests:
  tenant_isolation:
    skip: false
    main_user: admin@company.com
    natural_language_rule: |
      Ensure that standard members cannot access administrative features
      including user management, billing configuration, and system settings.
      Members should not be able to view or modify admin-only resources.

This configuration validates privilege escalation controls for API endpoints by replaying admin-accessible requests with member credentials and detecting unauthorized access.

Using Natural Language Rules¶

If you want to specify which endpoints should be tested (i.e. you have endpoints shared between both users), you can use natural language description and Escape AI will generate the list of Detectors that will be used. In order to view the generated detection rules, you can search for [Agentic - Tenant Isolation] in scan logs tab. The following configuration uses a natural language description:

authentication:
  presets:
    - type: bearer_token
      users:
        - username: user@tenant-a.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          main_user: true
        - username: user@tenant-b.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

security_tests:
  tenant_isolation:
    skip: false
    main_user: user@tenant-a.com
    natural_language_rule: |
      Ensure that users never recieve the same response. The endpoint /api/config is shared between all tenants and its not a tenant isolation issue.

Now you can also write your detection rules manually for more precision!

authentication:
  presets:
    - type: bearer_token
      users:
        - username: user@tenant-a.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          main_user: true
        - username: user@tenant-b.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

security_tests:
  tenant_isolation:
    skip: false
    main_user: user@tenant-a.com
    other_users:
      detect:
        - use_extraction: false
          regex: ^(?!/api/config).*$
          if: schema.path_ref
        - is: true
          if: request.is_authenticated
        - is: 200
          if: response.status_code
        - is: true
          if: helpers.fingerprints.same

Configuration Decision Tree¶

Should you use a single scan profile with multiple users, or multiple scan profiles?

Use a Single Scan Profile When¶

• All secondary users should be tested for their ability to access the Main User's data
• The Main User has the broadest feature access (ensuring maximum coverage)
• Testing direction is unidirectional (secondary users → Main User)

Use Multiple Scan Profiles When¶

• Bidirectional Privilege Escalation testing is required (asymmetric permissions)
• Different users have access to mutually exclusive features that must all be tested
• Independent exploration of multiple user roles is necessary for comprehensive coverage

Example Decision¶

Scenario: Testing a SaaS application with Admin, Manager, and Standard User roles

Question: Should this be one scan or three scans?

Answer: Depends on testing objectives:

• Single Scan (Privilege Escalation): If the goal is to validate that Manager and Standard User cannot access Admin data (one scan with Admin as Main User)
• Multiple Scans (Bidirectional Privilege Escalation): If the goal is to validate all three combinations (Admin→Manager, Manager→Admin, Standard→Manager requires three scans)
• Multiple Scans (Independent Exploration): If each role interacts with fundamentally different features requiring independent exploration (three separate scans)

Summary¶