feat: allow resolving Postman API resources against a self-hosted deployment - #3381

Problem

Newman hardcodes the Postman API host in lib/util.js, in two separate places:

POSTMAN_API_HOSTS = { 'api.postman.com': true, 'api.getpostman.com': true },
POSTMAN_API_URL   = 'https://api.postman.com',

This makes --postman-api-key unusable against a self-hosted (Postman Private Cloud) deployment, in two different ways:

Both surface the same Invalid API Key error, and nothing indicates the flag was ignored.

The only method that works today is embedding ?apikey= in the URL — which places the credential in argv, shell history, and every access log between the client and the server. For CI that is materially worse than a header.

Change

A configurable base URL, resolved as:

postmanApiBaseUrl run option → POSTMAN_API_BASE_URL env var → the public Postman API

The environment variable name matches the one the Postman CLI already uses, so a self-hosted user configures one variable for both tools.

• bin/newman.js — new --postman-api-base-url <url> option
• lib/util.js — resolveApiUrl() and isPostmanApiHost() helpers; fetchJson uses them
• lib/config/index.js — thread the new key through the common-options pick
• Covers both collections and environments uid resolution (POSTMAN_API_PATH_MAP)

Default behaviour is unchanged when no override is set.

Security note

The host allowlist exists to stop the API key being sent to an arbitrary host named on the command line. That property is preserved: the allowlist is widened only to the single host the user explicitly configured, never to any URL passed in. There is an explicit test for this:

should NOT send the API key to a host that is not configured

Usage

$ newman run $collectionUid --environment $environmentUid \
    --postman-api-key $apiKey \
    --postman-api-base-url https://api.postman.example.com

or

$ export POSTMAN_API_BASE_URL=https://api.postman.example.com
$ newman run $collectionUid --postman-api-key $apiKey

Tests

8 new cases in test/library/postman-api-key.test.js, following the existing nock/sinon pattern: uid resolution for collections and environments, env-var support, option-over-env precedence, trailing-slash tolerance, header attached for the configured host, header not attached for an unrelated host, and unchanged default behaviour.

16 passing   (8 existing + 8 new)

test-lint clean. test-unit 128 passing, test-library 77 passing. test-system has one pre-existing failure (npm publish > should not publish unnecessary files) that also fails on a clean develop checkout and is unrelated to this change.

Also verified end to end against a real self-hosted deployment — bare uid via env var, bare uid via flag, and a full self-hosted URL with --postman-api-key all fetch and execute; with no override set the run still goes to the public API and fails as before.

Docs

README gains a Self-hosted Postman deployments subsection, plus a note that the uid form sends the key as a header rather than a query parameter.