Newman Testing¶

Collection version

This guide covers the Authentic8 API Reference Collection (114 requests). The collection ships in postman_examples/ and is kept in sync with the SDK.

Newman is Postman's headless CLI runner. It lets you execute the Authentic8 API Reference Collection from the command line without opening Postman Desktop — useful for smoke testing, CI/CD pipelines, and scripted validation.

Prerequisites¶

macOS / LinuxCI/CD

npm install -g newman
newman --version

# GitHub Actions example
- name: Install Newman
  run: npm install -g newman

Your .env file must be populated with valid API tokens. See Configuration for the full list of required variables.

Quick Start¶

Load your .env and run the full collection against Production:

set -a && source .env && set +a

newman run postman_examples/Authentic8_API_Reference_Collection.postman_collection.json \
  -e postman_examples/environments/Authentic8_Production.postman_environment.json \
  --env-var "admin_token=$A8_ADMIN_TOKEN" \
  --env-var "sync_token=$A8_SYNC_TOKEN" \
  --env-var "file_token=$A8_FILE_TOKEN" \
  --env-var "log_token=$A8_LOG_TOKEN" \
  --env-var "scrape_token=$A8_SCRAPE_TOKEN" \
  --env-var "bucket_id=$A8_BUCKET_ID" \
  --env-var "org_name=$A8_TOP_ORG" \
  --env-var "username=$A8_CATCHALL_USER" \
  --timeout-request 30000

Use A8_TOP_ORG, not A8_ORG_VANITY_URL

The Postman org_name variable must be your API org name (e.g. MyCompany), set via A8_TOP_ORG. A8_ORG_VANITY_URL is your SSO vanity slug — a different value that the API does not accept as an org name.

Environment Files¶

Three environment files are included in postman_examples/environments/:

File	When to Use
`Authentic8_Production.postman_environment.json`	Live production API (`extapi.authentic8.com`)
`Authentic8_QA.postman_environment.json`	Internal QA environment (Authentic8 staff only)
`Authentic8_Engineering.postman_environment.json`	Internal engineering environment (Authentic8 staff only)

QA and Engineering environments

The QA and Engineering environment files are included for Authentic8 staff use. External customers should use the Production environment file only.

To target a different environment, swap the -e flag:

newman run postman_examples/Authentic8_API_Reference_Collection.postman_collection.json \
  -e postman_examples/environments/Authentic8_Engineering.postman_environment.json \
  --env-var "admin_token=$A8_ADMIN_TOKEN" \
  # ... remaining vars

Running Specific Folders¶

Use --folder to run a subset of the collection. Folder names match the numbered sections:

# Single API module
newman run ... --folder "3. Browsing Isolation"

# Multiple modules
newman run ... --folder "3. Browsing Isolation" --folder "4. File Storage"

# All non-flow folders (recommended for CI)
newman run ... \
  --folder "0. Getting Started" \
  --folder "1. Organization Management" \
  --folder "2. User Management" \
  --folder "3. Browsing Isolation" \
  --folder "4. File Storage" \
  --folder "5. Log Extraction" \
  --folder "6. Web Harvesting"

Folder	API Module	Token Required
`0. Getting Started`	Auth verification	`admin_token`
`1. Organization Management`	`OrgManagementAPI`	`admin_token`
`2. User Management`	`UserManagementAPI`	`sync_token`
`3. Browsing Isolation`	`BrowsingAPI`	`admin_token`
`4. File Storage`	`FileAPI`	`file_token`
`5. Log Extraction`	`LogExtractionAPI`	`log_token`
`6. Web Harvesting`	`HarvesterAPI`	`scrape_token`

Output Formats¶

Newman supports multiple reporters:

# Default CLI output
newman run ... --reporters cli

# JSON report for parsing
newman run ... \
  --reporters json \
  --reporter-json-export results.json

# JUnit XML for CI systems
newman run ... \
  --reporters junit \
  --reporter-junit-export results.xml

# Both CLI and JSON simultaneously
newman run ... \
  --reporters cli,json \
  --reporter-json-export results.json

Environment Variables Reference¶

All tokens are injected via --env-var at runtime. Never store real tokens in the committed environment JSON files.

`--env-var` key	Source `.env` variable	Used by
`admin_token`	`A8_ADMIN_TOKEN`	Browsing, Org Management
`sync_token`	`A8_SYNC_TOKEN`	User Management
`file_token`	`A8_FILE_TOKEN`	File Storage
`log_token`	`A8_LOG_TOKEN`	Log Extraction
`scrape_token`	`A8_SCRAPE_TOKEN`	Web Harvesting
`bucket_id`	`A8_BUCKET_ID`	File Storage
`org_name`	`A8_TOP_ORG`	Org and User Management, Log Extraction
`username`	`A8_CATCHALL_USER`	Browsing contexts

Auto-generated variables

test_org_name and test_sso_org_name are generated automatically by pre-request scripts in the Create Sub-Organization and Create SSO Config requests. You do not need to set these manually.

Known Limitations¶

The following requests use commands that require elevated token permissions not available on all accounts. Their test assertions are written to pass with either a successful result or a permission error, so they will not block your overall run:

Request	Command	Why it may return an error
Set Proxy Policy	`policy_proxies.set`	Requires elevated admin cert scope
Add Proxy Policy	`policy_proxies.add`	Same restriction
Delete Proxy Policy	`policy_proxies.delete`	Same restriction

The Flow sub-folders (Flow: Context Lifecycle, [Flow] Org Lifecycle, etc.) use pm.execution.setNextRequest() to chain requests. Postman Desktop's Collection Runner handles these correctly. Newman's linear runner stops at the first setNextRequest(null) call, so flow sequences are effectively skipped in Newman — use individual folder runs for those workflows.

CI/CD Integration¶

# .github/workflows/postman.yml
name: Postman API Tests

on:
  schedule:
    - cron: '0 8 * * 1-5'   # Weekdays at 8am UTC
  workflow_dispatch:

jobs:
  newman:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Newman
        run: npm install -g newman

      - name: Run Postman Collection
        env:
          A8_ADMIN_TOKEN: ${{ secrets.A8_ADMIN_TOKEN }}
          A8_SYNC_TOKEN: ${{ secrets.A8_SYNC_TOKEN }}
          A8_FILE_TOKEN: ${{ secrets.A8_FILE_TOKEN }}
          A8_LOG_TOKEN: ${{ secrets.A8_LOG_TOKEN }}
          A8_SCRAPE_TOKEN: ${{ secrets.A8_SCRAPE_TOKEN }}
          A8_BUCKET_ID: ${{ secrets.A8_BUCKET_ID }}
          A8_TOP_ORG: ${{ secrets.A8_TOP_ORG }}
          A8_CATCHALL_USER: ${{ secrets.A8_CATCHALL_USER }}
        run: |
          newman run postman_examples/Authentic8_API_Reference_Collection.postman_collection.json \
            -e postman_examples/environments/Authentic8_Production.postman_environment.json \
            --env-var "admin_token=$A8_ADMIN_TOKEN" \
            --env-var "sync_token=$A8_SYNC_TOKEN" \
            --env-var "file_token=$A8_FILE_TOKEN" \
            --env-var "log_token=$A8_LOG_TOKEN" \
            --env-var "scrape_token=$A8_SCRAPE_TOKEN" \
            --env-var "bucket_id=$A8_BUCKET_ID" \
            --env-var "org_name=$A8_TOP_ORG" \
            --env-var "username=$A8_CATCHALL_USER" \
            --timeout-request 30000 \
            --reporters cli,junit \
            --reporter-junit-export newman-results.xml

      - name: Publish Test Results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: newman-results.xml

Interpreting Results¶

A passing Newman run looks like:

┌─────────────────────────┬────────────────────┬────────────────────┐
│                         │           executed │             failed │
├─────────────────────────┼────────────────────┼────────────────────┤
│              iterations │                  1 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│                requests │                 23 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│            test-scripts │                 46 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│      prerequest-scripts │                 38 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│              assertions │                 88 │                  0 │
└─────────────────────────┴────────────────────┴────────────────────┘

Expected request count

Newman runs 23 requests (not 114) when using --folder flags for the 7 main sections. The full 114-request count includes Flow sub-folders, which Newman skips due to setNextRequest behavior. This is expected.

postman_examples/README.md — Collection structure and Postman Desktop setup
Authentication — Token types and how to obtain them
Configuration — .env setup and all A8_* variables