@postman-cse/onboarding-insights 2.0.0 → 2.1.0

package/README.md

@@ -4,7 +4,13 @@
 
 Links [Postman Insights](https://learning.postman.com/docs/insights/overview/) discovered services to [API Catalog](https://learning.postman.com/docs/api-catalog/overview/) workspaces and git repositories after deployment, so every service the Insights agent finds lands in your catalog with a collection, a repo link, and live telemetry.
 
-Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman-api-onboarding-action).
+Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman-api-onboarding-action); the composite action's README has the full [action-picker table](https://github.com/postman-cs/postman-api-onboarding-action#which-action-should-i-use).
+
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+- [Examples](#examples)
+- [Inputs](#inputs) / [Outputs](#outputs)
+- [How it works](#how-it-works)
 
 ## Prerequisites
 
@@ -16,19 +22,7 @@ Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman
 
 This action does **not** deploy the Insights agent, create workspaces, create environments, upload OpenAPI specs, or sync repo artifacts. It only links a service that Insights has already discovered.
 
-> **Credential requirement for the Insights linking steps.** The service discovery and git-link calls run on Postman's `api-catalog` service and accept a service-account access token. The Insights acknowledgment and application-binding steps run on the `akita` (Insights) service, which authenticates against a **Postman user identity** and answers `401 "Postman User not found"` for a service-account token. To complete the full link, supply a credential pair that carries a Postman user identity (a user's access token and user PMAK). A service-account-only pair from `postman-resolve-service-token-action` is sufficient for discovery and git linking but cannot finish the Insights acknowledgment.
-
-## Which action should I use?
-
-| Need | Action |
-| --- | --- |
-| Mint a service-account access token and team ID | [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action) |
-| Run the full workspace, collection, repo sync, and optional Insights pipeline | [Postman API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) |
-| Create a workspace, upload an OpenAPI spec, and generate collections | [Postman Onboarding: Workspace Bootstrap](https://github.com/postman-cs/postman-bootstrap-action) |
-| Sync Postman artifacts, mocks, monitors, and CI files back to the repo | [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) |
-| Link an already discovered Insights service to an existing workspace | [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) |
-| Discover OpenAPI specs from AWS services | [Postman Onboarding: AWS Spec Discovery](https://github.com/postman-cs/postman-aws-spec-discovery-action) |
-| Apply a curated smoke flow to an existing Smoke collection | [Postman Onboarding: Smoke Flow](https://github.com/postman-cs/postman-smoke-flow-action) |
+> **Credential requirement for the Insights linking steps.** The service discovery and git-link calls run on the `api-catalog` service and accept a service-account access token. The Insights acknowledgment and application-binding steps run on the `akita` (Insights) service, which authenticates against a **Postman user identity** and answers `401 "Postman User not found"` for a service-account token. To complete the full link, supply a credential pair that carries a Postman user identity (a user's access token and user PMAK). A service-account-only pair from `postman-resolve-service-token-action` is sufficient for discovery and git linking but cannot finish the Insights acknowledgment.
 
 ## Usage
 
@@ -209,7 +203,7 @@ See [CLI Usage](docs/cli.md) for provider auto-detection, output formats, and Gi
 | `system-environment-id` | Postman system environment UUID for service-level Insights acknowledgment | No |  |
 | `cluster-name` | Insights cluster name. When set, matches {cluster-name}/{project-name} exactly in discovered services | No |  |
 | `repo-url` | Repository URL for Git onboarding. Auto-detected from CI context when omitted. | No |  |
-| `postman-access-token` | Postman access token (x-access-token) for the Bifrost linking calls. The api-catalog discovery and git-link steps accept a service-account token (mint it with postman-resolve-service-token-action); the Insights (akita) acknowledgment and application-binding steps require a token carrying a Postman user identity — a service-account token answers 401 "Postman User not found" there. | Yes |  |
+| `postman-access-token` | Postman access token (x-access-token) for the Bifrost linking calls. When omitted, the action mints a service-account token from postman-api-key. The api-catalog discovery and git-link steps accept a service-account token (mint it with postman-resolve-service-token-action); the Insights (akita) acknowledgment and application-binding steps require a token carrying a Postman user identity — a service-account token answers 401 "Postman User not found" there. | No |  |
 | `postman-team-id` | Explicit Postman team ID for org-mode integration request headers. When omitted, x-entity-team-id is not sent. | No |  |
 | `github-token` | Optional GitHub token passed as git_api_key when repository auth is required by onboarding/git | No |  |
 | `postman-api-key` | Service-account Postman API key (PMAK-*) for the application binding call. Auto-created from postman-access-token when omitted or invalid after a clear 401/403 validation failure. | No |  |
@@ -238,11 +232,19 @@ Failures set `status=error` before the action exits.
 
 ## How it works
 
+```mermaid
+flowchart LR
+    D["Discovery poll<br/>discovered-services list"] --> P["Catalog prep<br/>prepare-collection"]
+    P --> G["Git link<br/>service to repository"]
+    G --> A["Acknowledgment<br/>onboard + workspace ack"]
+    A --> B["Binding<br/>application binding +<br/>team verification token"]
+```
+
 **Discovery poll.** The action polls the API Catalog discovered-services list at the configured interval until a service matching `{cluster-name}/{project-name}` appears (suffix matching when `cluster-name` is omitted) or the timeout is reached.
 
 **Catalog prep.** It then calls `POST /api/v1/onboarding/prepare-collection` to create the API Catalog collection entry for the discovered service in your workspace.
 
-**Git link.** `POST /api/v1/onboarding/git` with `via_integrations: false` links the service to the GitHub repository (`repo-url` input, auto-detected from CI context when omitted; `github-token` is passed as `git_api_key` only when the endpoint requires repository auth). Postman's [connect code](https://learning.postman.com/docs/api-catalog/connect/code/) docs cover the product workflow this binding supports.
+**Git link.** `POST /api/v1/onboarding/git` with `via_integrations: false` links the service to the GitHub repository (`repo-url` input, auto-detected from CI context when omitted; `github-token` is passed as `git_api_key` only when the endpoint requires repository auth). The [connect code](https://learning.postman.com/docs/api-catalog/connect/code/) docs cover the product workflow this binding supports.
 
 **Acknowledgment.** The action resolves the `svc_*` Akita service ID, marks the service as managed (`POST /v2/api-catalog/services/onboard`), and acknowledges the workspace (`POST /v2/workspaces/{id}/onboarding/acknowledge`) to activate the Insights project.
 
@@ -252,71 +254,14 @@ For local builds, contract smoke monitoring, and release channels, see [Developm
 
 ## Resources
 
-### The suite
-
-| Action | Role |
-| --- | --- |
-| [Postman API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) | Entry point: chains workspace bootstrap, repo sync, and optional Insights linking |
-| [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action) | Mints the service-account access token and team ID |
-| [Postman Onboarding: AWS Spec Discovery](https://github.com/postman-cs/postman-aws-spec-discovery-action) | Discovers and exports API specs from AWS services |
-| [Postman Onboarding: Workspace Bootstrap](https://github.com/postman-cs/postman-bootstrap-action) | Creates the workspace, uploads the spec, generates collections |
-| [Postman Onboarding: Smoke Flow](https://github.com/postman-cs/postman-smoke-flow-action) | Applies a curated flow.yaml to the Smoke collection |
-| [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) | Exports artifacts into the repo and wires CI, mocks, and monitors |
-| [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) | Links Insights discovered services to the workspace |
-
-- [postman-resolve-service-token-action](https://github.com/postman-cs/postman-resolve-service-token-action): mints a service-account access token and team ID.
-- [postman-api-onboarding-action](https://github.com/postman-cs/postman-api-onboarding-action): composite action that orchestrates the onboarding pipeline.
-- [postman-bootstrap-action](https://github.com/postman-cs/postman-bootstrap-action): workspace provisioning, spec upload, and collection generation.
-- [postman-smoke-flow-action](https://github.com/postman-cs/postman-smoke-flow-action): applies a curated flow.yaml to the canonical Smoke collection.
-- [postman-repo-sync-action](https://github.com/postman-cs/postman-repo-sync-action): artifact sync, environments, mocks, monitors, and CI templates.
-- [postman-aws-spec-discovery-action](https://github.com/postman-cs/postman-aws-spec-discovery-action): discovers API specs from AWS.
 - npm package: [@postman-cse/onboarding-insights](https://www.npmjs.com/package/@postman-cse/onboarding-insights)
+- Docs in this repo: [Credentials and Identity](docs/credentials.md), [Development and Operations](docs/development.md), [CLI usage](docs/cli.md)
+- Marketplace docs: [Support](SUPPORT.md), [Security Policy](SECURITY.md), [Release Policy](RELEASE_POLICY.md)
 - Postman Learning Center: [Insights overview](https://learning.postman.com/docs/insights/overview/), [connect Insights](https://learning.postman.com/docs/api-catalog/connect/insights/), [Insights API Catalog agent reference](https://learning.postman.com/docs/insights/reference/agent/api-catalog/), [API Catalog overview](https://learning.postman.com/docs/api-catalog/overview/), [connect code](https://learning.postman.com/docs/api-catalog/connect/code/)
-- [Credentials and Identity](docs/credentials.md)
-- [Development and Operations](docs/development.md)
-- [Support](SUPPORT.md)
-- [Security Policy](SECURITY.md)
-- [Release Policy](RELEASE_POLICY.md)
-
 
 ## Telemetry
 
-This action sends a single non-identifying usage event when a run completes, so the
-Postman team can measure adoption across CI systems. The event contains the
-action name and version, your Postman team ID, the detected CI provider and
-runner kind, the run outcome, the CI run identifier, an event timestamp, and a one-way SHA-256 hash of the repository
-identifier. Each event also carries a schema version and a constant event marker (always `completion`). The Postman team ID is sent in the clear on a legitimate-interest
-basis to measure product adoption.
-
-The `events.pm-cse.dev` endpoint is operated by the Postman Customer Success
-Engineering team. Postman, Inc. processes these events only to measure
-onboarding adoption in aggregate, retains them only as aggregated counts for
-product-adoption trend analysis, and includes no payload field that identifies
-an individual person.
-
-It never sends API keys, access tokens, spec content, workspace or repository
-names, or any personal data. It is fire-and-forget with a hard
-timeout and can never block or fail your pipeline. Corporate HTTP and HTTPS
-proxies are honored through the standard `HTTPS_PROXY`, `HTTP_PROXY`, and
-`NO_PROXY` environment variables.
-
-Disable it by setting either environment variable in your CI:
-
-```sh
-POSTMAN_ACTIONS_TELEMETRY=off
-# or the cross-tool standard
-DO_NOT_TRACK=1
-```
-
-Telemetry is also skipped automatically when no Postman team ID can be resolved.
-
-A run that ends in the `not-found` state (no matching Insights project) is
-recorded with a `failure` outcome.
-
-Events are sent over HTTPS to `https://events.pm-cse.dev/v1/events`. To
-allowlist this destination on a restricted network, or to route events to a
-collector you operate, set the `POSTMAN_ACTIONS_TELEMETRY_ENDPOINT` environment
-variable to your own URL.
+The action sends one anonymous usage event per run (action name/version, outcome, coarse CI metadata; never secrets, spec content, or repo names). A run ending in the `not-found` state is recorded with a `failure` outcome. Disable with `POSTMAN_ACTIONS_TELEMETRY=off` or `DO_NOT_TRACK=1`; route events to your own collector with `POSTMAN_ACTIONS_TELEMETRY_ENDPOINT`.
 
 ## License
 

package/action.yml

@@ -24,8 +24,8 @@ inputs:
     description: 'Repository URL for Git onboarding. Auto-detected from CI context when omitted.'
     required: false
   postman-access-token:
-    description: 'Postman access token (x-access-token) for the Bifrost linking calls. The api-catalog discovery and git-link steps accept a service-account token (mint it with postman-resolve-service-token-action); the Insights (akita) acknowledgment and application-binding steps require a token carrying a Postman user identity — a service-account token answers 401 "Postman User not found" there.'
-    required: true
+    description: 'Postman access token (x-access-token) for the Bifrost linking calls. When omitted, the action mints a service-account token from postman-api-key. The api-catalog discovery and git-link steps accept a service-account token (mint it with postman-resolve-service-token-action); the Insights (akita) acknowledgment and application-binding steps require a token carrying a Postman user identity — a service-account token answers 401 "Postman User not found" there.'
+    required: false
   postman-team-id:
     description: 'Explicit Postman team ID for org-mode integration request headers. When omitted, x-entity-team-id is not sent.'
     required: false

package/dist/action.cjs

@@ -20949,12 +20949,62 @@ function getIDToken(aud) {
 
 // src/lib/credential-identity.ts
 var sessionPath = "/api/sessions/current";
+var SESSION_MAX_ATTEMPTS = 3;
+var SESSION_RETRY_BASE_DELAY_MS = 500;
+var SESSION_RETRY_MAX_DELAY_MS = 8e3;
 var pmakMemo = /* @__PURE__ */ new Map();
 var sessionMemo = /* @__PURE__ */ new Map();
 var memoizedSessionIdentity;
+var memoizedSessionFailure;
+function defaultSessionSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function defaultRandom() {
+  return Math.random();
+}
+function parseRetryAfterMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return void 0;
+}
+function parseRateLimitResetMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) {
+    return void 0;
+  }
+  const seconds = Number(trimmed);
+  const nowSeconds = Date.now() / 1e3;
+  if (seconds > nowSeconds) {
+    return Math.max(0, (seconds - nowSeconds) * 1e3);
+  }
+  return seconds * 1e3;
+}
+function computeSessionRetryDelayMs(response, attempt, random) {
+  const headers = response?.headers;
+  const signal = parseRetryAfterMs(headers?.get("retry-after") ?? null) ?? parseRateLimitResetMs(
+    headers?.get("ratelimit-reset") ?? headers?.get("x-ratelimit-reset") ?? null
+  );
+  if (signal !== void 0) {
+    return Math.min(Math.max(0, signal), SESSION_RETRY_MAX_DELAY_MS);
+  }
+  const ceiling = Math.min(SESSION_RETRY_MAX_DELAY_MS, SESSION_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
+  return Math.round(random() * ceiling);
+}
 function getMemoizedSessionIdentity() {
   return memoizedSessionIdentity;
 }
+function getSessionResolutionFailure() {
+  return memoizedSessionFailure;
+}
 function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
@@ -21023,46 +21073,90 @@ async function resolveSessionIdentity(opts) {
   const memoKey = `${baseUrl}::${accessToken}`;
   let pending = sessionMemo.get(memoKey);
   if (!pending) {
-    pending = probeSessionIdentity(baseUrl, accessToken, opts.fetchImpl ?? fetch);
+    pending = probeSessionIdentity(
+      baseUrl,
+      accessToken,
+      opts.fetchImpl ?? fetch,
+      Math.max(1, opts.maxAttempts ?? SESSION_MAX_ATTEMPTS),
+      opts.sleepImpl ?? defaultSessionSleep,
+      opts.randomImpl ?? defaultRandom
+    );
     sessionMemo.set(memoKey, pending);
   }
   return pending;
 }
-async function probeSessionIdentity(baseUrl, accessToken, fetchImpl) {
+async function parseSessionResponse(response) {
+  let payload;
   try {
-    const response = await fetchImpl(`${baseUrl}${sessionPath}`, {
-      method: "GET",
-      headers: { "x-access-token": accessToken }
-    });
-    if (!response.ok) {
-      return void 0;
-    }
-    const payload = asRecord(await response.json());
-    if (!payload) {
-      return void 0;
-    }
-    const root = asRecord(payload.session) ?? payload;
-    const identity = asRecord(root.identity);
-    const data = asRecord(root.data);
-    const user = asRecord(data?.user);
-    const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
-    const singleRole = coerceText(user?.role);
-    const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
-    const resolved = {
-      source: "iapub/sessions",
-      userId: coerceId(identity?.user) ?? coerceId(user?.id),
-      fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
-      teamId: coerceId(identity?.team),
-      teamName: coerceText(user?.teamName),
-      teamDomain: coerceText(identity?.domain),
-      ...roles ? { roles } : {},
-      consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
-    };
-    memoizedSessionIdentity = resolved;
-    return resolved;
+    payload = asRecord(await response.json());
   } catch {
     return void 0;
   }
+  if (!payload) {
+    return void 0;
+  }
+  const root = asRecord(payload.session) ?? payload;
+  const identity = asRecord(root.identity);
+  const data = asRecord(root.data);
+  const user = asRecord(data?.user);
+  const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
+  const singleRole = coerceText(user?.role);
+  const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
+  return {
+    source: "iapub/sessions",
+    userId: coerceId(identity?.user) ?? coerceId(user?.id),
+    fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
+    teamId: coerceId(identity?.team),
+    teamName: coerceText(user?.teamName),
+    teamDomain: coerceText(identity?.domain),
+    ...roles ? { roles } : {},
+    consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
+  };
+}
+async function probeSessionIdentity(baseUrl, accessToken, fetchImpl, maxAttempts, sleepImpl, random) {
+  let failure = "unavailable";
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}${sessionPath}`, {
+        method: "GET",
+        headers: { "x-access-token": accessToken }
+      });
+    } catch {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(void 0, attempt, random));
+        continue;
+      }
+      break;
+    }
+    if (response.ok) {
+      const resolved = await parseSessionResponse(response);
+      if (resolved) {
+        memoizedSessionIdentity = resolved;
+        memoizedSessionFailure = void 0;
+        return resolved;
+      }
+      failure = "unavailable";
+      break;
+    }
+    if (response.status === 401 || response.status === 403) {
+      failure = "auth";
+      break;
+    }
+    if (response.status === 429 || response.status >= 500) {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(response, attempt, random));
+        continue;
+      }
+      break;
+    }
+    failure = "unavailable";
+    break;
+  }
+  memoizedSessionFailure = failure;
+  return void 0;
 }
 function describeTeam(id) {
   const label = id?.teamName ?? id?.teamDomain;
@@ -21155,7 +21249,9 @@ async function runCredentialPreflight(args) {
     session = await resolveSessionIdentity({
       iapubBaseUrl: args.iapubBaseUrl,
       accessToken,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      ...args.sleepImpl ? { sleepImpl: args.sleepImpl } : {},
+      ...args.randomImpl ? { randomImpl: args.randomImpl } : {}
     });
   } catch (error2) {
     args.log.warning(
@@ -21175,11 +21271,20 @@ async function runCredentialPreflight(args) {
       );
     }
   } else {
+    const failure = getSessionResolutionFailure();
+    const detail = failure === "auth" ? "the access token was rejected by iapub (401/403), so it is invalid or expired. Re-mint it with postman-resolve-service-token-action (or POST https://api.getpostman.com/service-account-tokens) and re-run." : "iapub was unreachable after retries (network or 5xx). This is usually transient; re-run the job.";
+    const base = "postman: credential preflight could not resolve the access-token session identity from iapub: " + detail;
+    if (args.mode === "enforce") {
+      throw new Error(
+        mask(
+          `${base} (credential-preflight: enforce requires a resolvable session identity; use credential-preflight: warn to continue with reactive error guidance only.)`
+        )
+      );
+    }
     args.log.warning(
-      mask(
-        "postman: credential preflight could not resolve the access-token session identity from iapub; continuing with reactive error guidance only"
-      )
+      mask(`${base} Continuing with reactive error guidance only (credential-preflight: warn).`)
     );
+    return;
   }
   const result = crossCheckIdentities({
     pmak,
@@ -21591,6 +21696,53 @@ var AccessTokenProvider = class {
     return token;
   }
 };
+async function describeMintFailure(mintError, apiKey, apiBaseUrl, fetchImpl) {
+  const raw = mintError instanceof Error ? mintError.message : String(mintError);
+  const rejected = /HTTP 40[13]|PMAK rejected/.test(raw);
+  if (!rejected) {
+    return raw;
+  }
+  try {
+    const me = await fetchImpl(`${apiBaseUrl}/me`, { headers: { "x-api-key": apiKey } });
+    if (me.ok) {
+      const body = await me.json().catch(() => void 0);
+      const user = body?.user;
+      const looksPersonal = Boolean(user && (user.username || user.email));
+      if (looksPersonal) {
+        return "Personal API key detected, cannot mint a service-account access token. POST /service-account-tokens only accepts a SERVICE-ACCOUNT API key; this postman-api-key belongs to a user account" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". Create a service account in Team Settings and use its PMAK, or mint the token elsewhere and pass postman-access-token.";
+      }
+      return "The postman-api-key authenticates (GET /me OK) but was rejected by POST /service-account-tokens" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". The service account likely lacks permission to mint access tokens, or service accounts are restricted for this team. Check the service account role in Team Settings, or pass a pre-minted postman-access-token.";
+    }
+    return "The postman-api-key is invalid, disabled, or expired (rejected by both POST /service-account-tokens and GET /me). Generate a fresh service-account PMAK in Team Settings and update the secret.";
+  } catch {
+    return raw;
+  }
+}
+async function mintAccessTokenIfNeeded(inputs, log, setSecret2, fetchImpl = fetch) {
+  if (inputs.postmanAccessToken || !inputs.postmanApiKey) {
+    return;
+  }
+  const apiBaseUrl = String(
+    inputs.postmanApiBase || POSTMAN_ENDPOINT_PROFILES.prod.apiBaseUrl
+  ).replace(/\/+$/, "");
+  const provider = new AccessTokenProvider({
+    apiKey: inputs.postmanApiKey,
+    apiBaseUrl,
+    fetchImpl,
+    onToken: (token) => setSecret2?.(token)
+  });
+  try {
+    inputs.postmanAccessToken = await provider.refresh();
+    log.info(
+      "postman: no postman-access-token configured - minted a short-lived service-account access token from the postman-api-key."
+    );
+  } catch (error2) {
+    const diagnosis = await describeMintFailure(error2, inputs.postmanApiKey, apiBaseUrl, fetchImpl);
+    log.warning(
+      "postman: could not mint an access token from the postman-api-key. " + diagnosis + " Continuing without an access token - access-token-only functionality will be unavailable unless postman-access-token is provided."
+    );
+  }
+}
 
 // src/lib/bifrost-client.ts
 var DEFAULT_BIFROST_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.bifrostBaseUrl;
@@ -22249,7 +22401,7 @@ function resolveActionVersion(explicit) {
   if (explicit) {
     return explicit;
   }
-  return "2.0.0" ? "2.0.0" : "unknown";
+  return typeof __ACTION_VERSION__ !== "undefined" && __ACTION_VERSION__ ? __ACTION_VERSION__ : "unknown";
 }
 function telemetryDisabled(env) {
   const flag = String(env.POSTMAN_ACTIONS_TELEMETRY ?? "").trim().toLowerCase();
@@ -22371,6 +22523,18 @@ function createTelemetryContext(options) {
   };
 }
 
+// src/action-version.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function resolveActionVersion2() {
+  try {
+    const raw = (0, import_node_fs.readFileSync)((0, import_node_path.join)(__dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/index.ts
 var POLL_TIMEOUT_MIN = 10;
 var POLL_TIMEOUT_MAX = 600;
@@ -22436,8 +22600,12 @@ function resolveInputs(env = process.env) {
   const projectName = get("project-name");
   if (!projectName) throw new Error("project-name is required");
   const postmanAccessToken = get("postman-access-token");
-  if (!postmanAccessToken) throw new Error("postman-access-token is required");
   const postmanApiKey = get("postman-api-key");
+  if (!postmanAccessToken && !postmanApiKey) {
+    throw new Error(
+      "postman-access-token is required (or provide a service-account postman-api-key so the action can mint one)."
+    );
+  }
   const postmanTeamId = get("postman-team-id") || env.POSTMAN_TEAM_ID?.trim() || "";
   const workspaceId = get("workspace-id") || env.POSTMAN_WORKSPACE_ID?.trim() || "";
   if (!workspaceId) {
@@ -22677,7 +22845,14 @@ async function runAction() {
   for (const [key, value] of Object.entries(planned)) {
     setOutput(key, value);
   }
-  setSecret(inputs.postmanAccessToken);
+  const mintHolder = {
+    postmanAccessToken: inputs.postmanAccessToken,
+    postmanApiKey: inputs.postmanApiKey,
+    postmanApiBase: inputs.postmanApiBase
+  };
+  await mintAccessTokenIfNeeded(mintHolder, core_exports, (secret) => setSecret(secret));
+  inputs.postmanAccessToken = mintHolder.postmanAccessToken;
+  if (inputs.postmanAccessToken) setSecret(inputs.postmanAccessToken);
   if (inputs.postmanApiKey) setSecret(inputs.postmanApiKey);
   if (inputs.githubToken) setSecret(inputs.githubToken);
   const tokenProvider = createInsightsTokenProvider(inputs, core_exports);
@@ -22694,7 +22869,7 @@ async function runAction() {
     apiBaseUrl: inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE,
     onToken: (token) => setSecret(token)
   }) : tokenProvider;
-  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", logger: core_exports });
+  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", actionVersion: resolveActionVersion2(), logger: core_exports });
   telemetry.setTeamId(inputs.postmanTeamId || pmakIdentity?.teamId);
   let result;
   try {

package/dist/cli.cjs

@@ -18685,9 +18685,9 @@ __export(cli_exports, {
   toDotenv: () => toDotenv
 });
 module.exports = __toCommonJS(cli_exports);
-var import_node_fs = require("node:fs");
+var import_node_fs2 = require("node:fs");
 var import_promises = require("node:fs/promises");
-var import_node_path = __toESM(require("node:path"), 1);
+var import_node_path2 = __toESM(require("node:path"), 1);
 
 // src/lib/retry.ts
 function sleep(delayMs) {
@@ -18891,6 +18891,53 @@ var AccessTokenProvider = class {
     return token;
   }
 };
+async function describeMintFailure(mintError, apiKey, apiBaseUrl, fetchImpl) {
+  const raw = mintError instanceof Error ? mintError.message : String(mintError);
+  const rejected = /HTTP 40[13]|PMAK rejected/.test(raw);
+  if (!rejected) {
+    return raw;
+  }
+  try {
+    const me = await fetchImpl(`${apiBaseUrl}/me`, { headers: { "x-api-key": apiKey } });
+    if (me.ok) {
+      const body = await me.json().catch(() => void 0);
+      const user = body?.user;
+      const looksPersonal = Boolean(user && (user.username || user.email));
+      if (looksPersonal) {
+        return "Personal API key detected, cannot mint a service-account access token. POST /service-account-tokens only accepts a SERVICE-ACCOUNT API key; this postman-api-key belongs to a user account" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". Create a service account in Team Settings and use its PMAK, or mint the token elsewhere and pass postman-access-token.";
+      }
+      return "The postman-api-key authenticates (GET /me OK) but was rejected by POST /service-account-tokens" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". The service account likely lacks permission to mint access tokens, or service accounts are restricted for this team. Check the service account role in Team Settings, or pass a pre-minted postman-access-token.";
+    }
+    return "The postman-api-key is invalid, disabled, or expired (rejected by both POST /service-account-tokens and GET /me). Generate a fresh service-account PMAK in Team Settings and update the secret.";
+  } catch {
+    return raw;
+  }
+}
+async function mintAccessTokenIfNeeded(inputs, log, setSecret2, fetchImpl = fetch) {
+  if (inputs.postmanAccessToken || !inputs.postmanApiKey) {
+    return;
+  }
+  const apiBaseUrl = String(
+    inputs.postmanApiBase || POSTMAN_ENDPOINT_PROFILES.prod.apiBaseUrl
+  ).replace(/\/+$/, "");
+  const provider = new AccessTokenProvider({
+    apiKey: inputs.postmanApiKey,
+    apiBaseUrl,
+    fetchImpl,
+    onToken: (token) => setSecret2?.(token)
+  });
+  try {
+    inputs.postmanAccessToken = await provider.refresh();
+    log.info(
+      "postman: no postman-access-token configured - minted a short-lived service-account access token from the postman-api-key."
+    );
+  } catch (error2) {
+    const diagnosis = await describeMintFailure(error2, inputs.postmanApiKey, apiBaseUrl, fetchImpl);
+    log.warning(
+      "postman: could not mint an access token from the postman-api-key. " + diagnosis + " Continuing without an access token - access-token-only functionality will be unavailable unless postman-access-token is provided."
+    );
+  }
+}
 
 // node_modules/@actions/core/lib/core.js
 var core_exports = {};
@@ -21167,12 +21214,62 @@ function getIDToken(aud) {
 
 // src/lib/credential-identity.ts
 var sessionPath = "/api/sessions/current";
+var SESSION_MAX_ATTEMPTS = 3;
+var SESSION_RETRY_BASE_DELAY_MS = 500;
+var SESSION_RETRY_MAX_DELAY_MS = 8e3;
 var pmakMemo = /* @__PURE__ */ new Map();
 var sessionMemo = /* @__PURE__ */ new Map();
 var memoizedSessionIdentity;
+var memoizedSessionFailure;
+function defaultSessionSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function defaultRandom() {
+  return Math.random();
+}
+function parseRetryAfterMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return void 0;
+}
+function parseRateLimitResetMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) {
+    return void 0;
+  }
+  const seconds = Number(trimmed);
+  const nowSeconds = Date.now() / 1e3;
+  if (seconds > nowSeconds) {
+    return Math.max(0, (seconds - nowSeconds) * 1e3);
+  }
+  return seconds * 1e3;
+}
+function computeSessionRetryDelayMs(response, attempt, random) {
+  const headers = response?.headers;
+  const signal = parseRetryAfterMs(headers?.get("retry-after") ?? null) ?? parseRateLimitResetMs(
+    headers?.get("ratelimit-reset") ?? headers?.get("x-ratelimit-reset") ?? null
+  );
+  if (signal !== void 0) {
+    return Math.min(Math.max(0, signal), SESSION_RETRY_MAX_DELAY_MS);
+  }
+  const ceiling = Math.min(SESSION_RETRY_MAX_DELAY_MS, SESSION_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
+  return Math.round(random() * ceiling);
+}
 function getMemoizedSessionIdentity() {
   return memoizedSessionIdentity;
 }
+function getSessionResolutionFailure() {
+  return memoizedSessionFailure;
+}
 function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
@@ -21241,46 +21338,90 @@ async function resolveSessionIdentity(opts) {
   const memoKey = `${baseUrl}::${accessToken}`;
   let pending = sessionMemo.get(memoKey);
   if (!pending) {
-    pending = probeSessionIdentity(baseUrl, accessToken, opts.fetchImpl ?? fetch);
+    pending = probeSessionIdentity(
+      baseUrl,
+      accessToken,
+      opts.fetchImpl ?? fetch,
+      Math.max(1, opts.maxAttempts ?? SESSION_MAX_ATTEMPTS),
+      opts.sleepImpl ?? defaultSessionSleep,
+      opts.randomImpl ?? defaultRandom
+    );
     sessionMemo.set(memoKey, pending);
   }
   return pending;
 }
-async function probeSessionIdentity(baseUrl, accessToken, fetchImpl) {
+async function parseSessionResponse(response) {
+  let payload;
   try {
-    const response = await fetchImpl(`${baseUrl}${sessionPath}`, {
-      method: "GET",
-      headers: { "x-access-token": accessToken }
-    });
-    if (!response.ok) {
-      return void 0;
-    }
-    const payload = asRecord(await response.json());
-    if (!payload) {
-      return void 0;
-    }
-    const root = asRecord(payload.session) ?? payload;
-    const identity = asRecord(root.identity);
-    const data = asRecord(root.data);
-    const user = asRecord(data?.user);
-    const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
-    const singleRole = coerceText(user?.role);
-    const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
-    const resolved = {
-      source: "iapub/sessions",
-      userId: coerceId(identity?.user) ?? coerceId(user?.id),
-      fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
-      teamId: coerceId(identity?.team),
-      teamName: coerceText(user?.teamName),
-      teamDomain: coerceText(identity?.domain),
-      ...roles ? { roles } : {},
-      consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
-    };
-    memoizedSessionIdentity = resolved;
-    return resolved;
+    payload = asRecord(await response.json());
   } catch {
     return void 0;
   }
+  if (!payload) {
+    return void 0;
+  }
+  const root = asRecord(payload.session) ?? payload;
+  const identity = asRecord(root.identity);
+  const data = asRecord(root.data);
+  const user = asRecord(data?.user);
+  const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
+  const singleRole = coerceText(user?.role);
+  const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
+  return {
+    source: "iapub/sessions",
+    userId: coerceId(identity?.user) ?? coerceId(user?.id),
+    fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
+    teamId: coerceId(identity?.team),
+    teamName: coerceText(user?.teamName),
+    teamDomain: coerceText(identity?.domain),
+    ...roles ? { roles } : {},
+    consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
+  };
+}
+async function probeSessionIdentity(baseUrl, accessToken, fetchImpl, maxAttempts, sleepImpl, random) {
+  let failure = "unavailable";
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}${sessionPath}`, {
+        method: "GET",
+        headers: { "x-access-token": accessToken }
+      });
+    } catch {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(void 0, attempt, random));
+        continue;
+      }
+      break;
+    }
+    if (response.ok) {
+      const resolved = await parseSessionResponse(response);
+      if (resolved) {
+        memoizedSessionIdentity = resolved;
+        memoizedSessionFailure = void 0;
+        return resolved;
+      }
+      failure = "unavailable";
+      break;
+    }
+    if (response.status === 401 || response.status === 403) {
+      failure = "auth";
+      break;
+    }
+    if (response.status === 429 || response.status >= 500) {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(response, attempt, random));
+        continue;
+      }
+      break;
+    }
+    failure = "unavailable";
+    break;
+  }
+  memoizedSessionFailure = failure;
+  return void 0;
 }
 function describeTeam(id) {
   const label = id?.teamName ?? id?.teamDomain;
@@ -21373,7 +21514,9 @@ async function runCredentialPreflight(args) {
     session = await resolveSessionIdentity({
       iapubBaseUrl: args.iapubBaseUrl,
       accessToken,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      ...args.sleepImpl ? { sleepImpl: args.sleepImpl } : {},
+      ...args.randomImpl ? { randomImpl: args.randomImpl } : {}
     });
   } catch (error2) {
     args.log.warning(
@@ -21393,11 +21536,20 @@ async function runCredentialPreflight(args) {
       );
     }
   } else {
+    const failure = getSessionResolutionFailure();
+    const detail = failure === "auth" ? "the access token was rejected by iapub (401/403), so it is invalid or expired. Re-mint it with postman-resolve-service-token-action (or POST https://api.getpostman.com/service-account-tokens) and re-run." : "iapub was unreachable after retries (network or 5xx). This is usually transient; re-run the job.";
+    const base = "postman: credential preflight could not resolve the access-token session identity from iapub: " + detail;
+    if (args.mode === "enforce") {
+      throw new Error(
+        mask(
+          `${base} (credential-preflight: enforce requires a resolvable session identity; use credential-preflight: warn to continue with reactive error guidance only.)`
+        )
+      );
+    }
     args.log.warning(
-      mask(
-        "postman: credential preflight could not resolve the access-token session identity from iapub; continuing with reactive error guidance only"
-      )
+      mask(`${base} Continuing with reactive error guidance only (credential-preflight: warn).`)
     );
+    return;
   }
   const result = crossCheckIdentities({
     pmak,
@@ -22264,7 +22416,7 @@ function resolveActionVersion(explicit) {
   if (explicit) {
     return explicit;
   }
-  return "2.0.0" ? "2.0.0" : "unknown";
+  return typeof __ACTION_VERSION__ !== "undefined" && __ACTION_VERSION__ ? __ACTION_VERSION__ : "unknown";
 }
 function telemetryDisabled(env) {
   const flag = String(env.POSTMAN_ACTIONS_TELEMETRY ?? "").trim().toLowerCase();
@@ -22386,6 +22538,18 @@ function createTelemetryContext(options) {
   };
 }
 
+// src/action-version.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function resolveActionVersion2() {
+  try {
+    const raw = (0, import_node_fs.readFileSync)((0, import_node_path.join)(__dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/index.ts
 var POLL_TIMEOUT_MIN = 10;
 var POLL_TIMEOUT_MAX = 600;
@@ -22451,8 +22615,12 @@ function resolveInputs(env = process.env) {
   const projectName = get("project-name");
   if (!projectName) throw new Error("project-name is required");
   const postmanAccessToken = get("postman-access-token");
-  if (!postmanAccessToken) throw new Error("postman-access-token is required");
   const postmanApiKey = get("postman-api-key");
+  if (!postmanAccessToken && !postmanApiKey) {
+    throw new Error(
+      "postman-access-token is required (or provide a service-account postman-api-key so the action can mint one)."
+    );
+  }
   const postmanTeamId = get("postman-team-id") || env.POSTMAN_TEAM_ID?.trim() || "";
   const workspaceId = get("workspace-id") || env.POSTMAN_WORKSPACE_ID?.trim() || "";
   if (!workspaceId) {
@@ -22756,13 +22924,13 @@ async function writeOptionalFile(filePath, content) {
   if (!filePath) {
     return;
   }
-  const workspaceRoot = import_node_path.default.resolve(process.cwd());
-  const resolved = import_node_path.default.resolve(workspaceRoot, filePath);
-  const relative2 = import_node_path.default.relative(workspaceRoot, resolved);
-  if (relative2.startsWith("..") || import_node_path.default.isAbsolute(relative2)) {
+  const workspaceRoot = import_node_path2.default.resolve(process.cwd());
+  const resolved = import_node_path2.default.resolve(workspaceRoot, filePath);
+  const relative2 = import_node_path2.default.relative(workspaceRoot, resolved);
+  if (relative2.startsWith("..") || import_node_path2.default.isAbsolute(relative2)) {
     throw new Error(`Output path must stay within workspace: ${filePath}`);
   }
-  await (0, import_promises.mkdir)(import_node_path.default.dirname(resolved), { recursive: true });
+  await (0, import_promises.mkdir)(import_node_path2.default.dirname(resolved), { recursive: true });
   await (0, import_promises.writeFile)(resolved, content, "utf8");
 }
 function toOutputs(result) {
@@ -22780,7 +22948,14 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const config = parseCliArgs(argv, env);
   const inputs = resolveInputs(config.inputEnv);
   const reporter = new ConsoleReporter();
-  reporter.setSecret(inputs.postmanAccessToken);
+  const mintHolder = {
+    postmanAccessToken: inputs.postmanAccessToken,
+    postmanApiKey: inputs.postmanApiKey,
+    postmanApiBase: inputs.postmanApiBase
+  };
+  await mintAccessTokenIfNeeded(mintHolder, reporter, (secret) => reporter.setSecret(secret));
+  inputs.postmanAccessToken = mintHolder.postmanAccessToken;
+  if (inputs.postmanAccessToken) reporter.setSecret(inputs.postmanAccessToken);
   if (inputs.postmanApiKey) {
     reporter.setSecret(inputs.postmanApiKey);
   }
@@ -22805,7 +22980,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
     apiBaseUrl: inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE,
     onToken: (token) => reporter.setSecret(token)
   }) : tokenProvider;
-  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", logger: reporter });
+  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", actionVersion: resolveActionVersion2(), logger: reporter });
   telemetry.setTeamId(inputs.postmanTeamId || pmakIdentity?.teamId);
   if (apiKey) {
     reporter.setSecret(apiKey);
@@ -22850,9 +23025,9 @@ function isEntrypoint(currentPath, entrypointPath) {
     return false;
   }
   try {
-    return (0, import_node_fs.realpathSync)(currentPath) === (0, import_node_fs.realpathSync)(entrypointPath);
+    return (0, import_node_fs2.realpathSync)(currentPath) === (0, import_node_fs2.realpathSync)(entrypointPath);
   } catch {
-    return import_node_path.default.resolve(currentPath) === import_node_path.default.resolve(entrypointPath);
+    return import_node_path2.default.resolve(currentPath) === import_node_path2.default.resolve(entrypointPath);
   }
 }
 if (isEntrypoint(currentModulePath, entrypoint)) {

package/dist/index.cjs

@@ -20971,12 +20971,62 @@ function getIDToken(aud) {
 
 // src/lib/credential-identity.ts
 var sessionPath = "/api/sessions/current";
+var SESSION_MAX_ATTEMPTS = 3;
+var SESSION_RETRY_BASE_DELAY_MS = 500;
+var SESSION_RETRY_MAX_DELAY_MS = 8e3;
 var pmakMemo = /* @__PURE__ */ new Map();
 var sessionMemo = /* @__PURE__ */ new Map();
 var memoizedSessionIdentity;
+var memoizedSessionFailure;
+function defaultSessionSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function defaultRandom() {
+  return Math.random();
+}
+function parseRetryAfterMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return void 0;
+}
+function parseRateLimitResetMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) {
+    return void 0;
+  }
+  const seconds = Number(trimmed);
+  const nowSeconds = Date.now() / 1e3;
+  if (seconds > nowSeconds) {
+    return Math.max(0, (seconds - nowSeconds) * 1e3);
+  }
+  return seconds * 1e3;
+}
+function computeSessionRetryDelayMs(response, attempt, random) {
+  const headers = response?.headers;
+  const signal = parseRetryAfterMs(headers?.get("retry-after") ?? null) ?? parseRateLimitResetMs(
+    headers?.get("ratelimit-reset") ?? headers?.get("x-ratelimit-reset") ?? null
+  );
+  if (signal !== void 0) {
+    return Math.min(Math.max(0, signal), SESSION_RETRY_MAX_DELAY_MS);
+  }
+  const ceiling = Math.min(SESSION_RETRY_MAX_DELAY_MS, SESSION_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
+  return Math.round(random() * ceiling);
+}
 function getMemoizedSessionIdentity() {
   return memoizedSessionIdentity;
 }
+function getSessionResolutionFailure() {
+  return memoizedSessionFailure;
+}
 function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
@@ -21045,46 +21095,90 @@ async function resolveSessionIdentity(opts) {
   const memoKey = `${baseUrl}::${accessToken}`;
   let pending = sessionMemo.get(memoKey);
   if (!pending) {
-    pending = probeSessionIdentity(baseUrl, accessToken, opts.fetchImpl ?? fetch);
+    pending = probeSessionIdentity(
+      baseUrl,
+      accessToken,
+      opts.fetchImpl ?? fetch,
+      Math.max(1, opts.maxAttempts ?? SESSION_MAX_ATTEMPTS),
+      opts.sleepImpl ?? defaultSessionSleep,
+      opts.randomImpl ?? defaultRandom
+    );
     sessionMemo.set(memoKey, pending);
   }
   return pending;
 }
-async function probeSessionIdentity(baseUrl, accessToken, fetchImpl) {
+async function parseSessionResponse(response) {
+  let payload;
   try {
-    const response = await fetchImpl(`${baseUrl}${sessionPath}`, {
-      method: "GET",
-      headers: { "x-access-token": accessToken }
-    });
-    if (!response.ok) {
-      return void 0;
-    }
-    const payload = asRecord(await response.json());
-    if (!payload) {
-      return void 0;
-    }
-    const root = asRecord(payload.session) ?? payload;
-    const identity = asRecord(root.identity);
-    const data = asRecord(root.data);
-    const user = asRecord(data?.user);
-    const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
-    const singleRole = coerceText(user?.role);
-    const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
-    const resolved = {
-      source: "iapub/sessions",
-      userId: coerceId(identity?.user) ?? coerceId(user?.id),
-      fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
-      teamId: coerceId(identity?.team),
-      teamName: coerceText(user?.teamName),
-      teamDomain: coerceText(identity?.domain),
-      ...roles ? { roles } : {},
-      consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
-    };
-    memoizedSessionIdentity = resolved;
-    return resolved;
+    payload = asRecord(await response.json());
   } catch {
     return void 0;
   }
+  if (!payload) {
+    return void 0;
+  }
+  const root = asRecord(payload.session) ?? payload;
+  const identity = asRecord(root.identity);
+  const data = asRecord(root.data);
+  const user = asRecord(data?.user);
+  const roleEntries = Array.isArray(user?.roles) ? user.roles.map((entry) => coerceText(entry) ?? coerceId(entry)).filter((entry) => Boolean(entry)) : [];
+  const singleRole = coerceText(user?.role);
+  const roles = roleEntries.length > 0 ? roleEntries : singleRole ? [singleRole] : void 0;
+  return {
+    source: "iapub/sessions",
+    userId: coerceId(identity?.user) ?? coerceId(user?.id),
+    fullName: coerceText(user?.fullName) ?? coerceText(user?.name) ?? coerceText(user?.username),
+    teamId: coerceId(identity?.team),
+    teamName: coerceText(user?.teamName),
+    teamDomain: coerceText(identity?.domain),
+    ...roles ? { roles } : {},
+    consumerType: coerceText(root.consumerType) ?? coerceText(data?.consumerType) ?? coerceText(user?.consumerType)
+  };
+}
+async function probeSessionIdentity(baseUrl, accessToken, fetchImpl, maxAttempts, sleepImpl, random) {
+  let failure = "unavailable";
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(`${baseUrl}${sessionPath}`, {
+        method: "GET",
+        headers: { "x-access-token": accessToken }
+      });
+    } catch {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(void 0, attempt, random));
+        continue;
+      }
+      break;
+    }
+    if (response.ok) {
+      const resolved = await parseSessionResponse(response);
+      if (resolved) {
+        memoizedSessionIdentity = resolved;
+        memoizedSessionFailure = void 0;
+        return resolved;
+      }
+      failure = "unavailable";
+      break;
+    }
+    if (response.status === 401 || response.status === 403) {
+      failure = "auth";
+      break;
+    }
+    if (response.status === 429 || response.status >= 500) {
+      failure = "unavailable";
+      if (attempt < maxAttempts) {
+        await sleepImpl(computeSessionRetryDelayMs(response, attempt, random));
+        continue;
+      }
+      break;
+    }
+    failure = "unavailable";
+    break;
+  }
+  memoizedSessionFailure = failure;
+  return void 0;
 }
 function describeTeam(id) {
   const label = id?.teamName ?? id?.teamDomain;
@@ -21177,7 +21271,9 @@ async function runCredentialPreflight(args) {
     session = await resolveSessionIdentity({
       iapubBaseUrl: args.iapubBaseUrl,
       accessToken,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      ...args.sleepImpl ? { sleepImpl: args.sleepImpl } : {},
+      ...args.randomImpl ? { randomImpl: args.randomImpl } : {}
     });
   } catch (error2) {
     args.log.warning(
@@ -21197,11 +21293,20 @@ async function runCredentialPreflight(args) {
       );
     }
   } else {
+    const failure = getSessionResolutionFailure();
+    const detail = failure === "auth" ? "the access token was rejected by iapub (401/403), so it is invalid or expired. Re-mint it with postman-resolve-service-token-action (or POST https://api.getpostman.com/service-account-tokens) and re-run." : "iapub was unreachable after retries (network or 5xx). This is usually transient; re-run the job.";
+    const base = "postman: credential preflight could not resolve the access-token session identity from iapub: " + detail;
+    if (args.mode === "enforce") {
+      throw new Error(
+        mask(
+          `${base} (credential-preflight: enforce requires a resolvable session identity; use credential-preflight: warn to continue with reactive error guidance only.)`
+        )
+      );
+    }
     args.log.warning(
-      mask(
-        "postman: credential preflight could not resolve the access-token session identity from iapub; continuing with reactive error guidance only"
-      )
+      mask(`${base} Continuing with reactive error guidance only (credential-preflight: warn).`)
     );
+    return;
   }
   const result = crossCheckIdentities({
     pmak,
@@ -21613,6 +21718,53 @@ var AccessTokenProvider = class {
     return token;
   }
 };
+async function describeMintFailure(mintError, apiKey, apiBaseUrl, fetchImpl) {
+  const raw = mintError instanceof Error ? mintError.message : String(mintError);
+  const rejected = /HTTP 40[13]|PMAK rejected/.test(raw);
+  if (!rejected) {
+    return raw;
+  }
+  try {
+    const me = await fetchImpl(`${apiBaseUrl}/me`, { headers: { "x-api-key": apiKey } });
+    if (me.ok) {
+      const body = await me.json().catch(() => void 0);
+      const user = body?.user;
+      const looksPersonal = Boolean(user && (user.username || user.email));
+      if (looksPersonal) {
+        return "Personal API key detected, cannot mint a service-account access token. POST /service-account-tokens only accepts a SERVICE-ACCOUNT API key; this postman-api-key belongs to a user account" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". Create a service account in Team Settings and use its PMAK, or mint the token elsewhere and pass postman-access-token.";
+      }
+      return "The postman-api-key authenticates (GET /me OK) but was rejected by POST /service-account-tokens" + (user?.teamId ? ` (team ${user.teamId})` : "") + ". The service account likely lacks permission to mint access tokens, or service accounts are restricted for this team. Check the service account role in Team Settings, or pass a pre-minted postman-access-token.";
+    }
+    return "The postman-api-key is invalid, disabled, or expired (rejected by both POST /service-account-tokens and GET /me). Generate a fresh service-account PMAK in Team Settings and update the secret.";
+  } catch {
+    return raw;
+  }
+}
+async function mintAccessTokenIfNeeded(inputs, log, setSecret2, fetchImpl = fetch) {
+  if (inputs.postmanAccessToken || !inputs.postmanApiKey) {
+    return;
+  }
+  const apiBaseUrl = String(
+    inputs.postmanApiBase || POSTMAN_ENDPOINT_PROFILES.prod.apiBaseUrl
+  ).replace(/\/+$/, "");
+  const provider = new AccessTokenProvider({
+    apiKey: inputs.postmanApiKey,
+    apiBaseUrl,
+    fetchImpl,
+    onToken: (token) => setSecret2?.(token)
+  });
+  try {
+    inputs.postmanAccessToken = await provider.refresh();
+    log.info(
+      "postman: no postman-access-token configured - minted a short-lived service-account access token from the postman-api-key."
+    );
+  } catch (error2) {
+    const diagnosis = await describeMintFailure(error2, inputs.postmanApiKey, apiBaseUrl, fetchImpl);
+    log.warning(
+      "postman: could not mint an access token from the postman-api-key. " + diagnosis + " Continuing without an access token - access-token-only functionality will be unavailable unless postman-access-token is provided."
+    );
+  }
+}
 
 // src/lib/bifrost-client.ts
 var DEFAULT_BIFROST_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.bifrostBaseUrl;
@@ -22271,7 +22423,7 @@ function resolveActionVersion(explicit) {
   if (explicit) {
     return explicit;
   }
-  return "2.0.0" ? "2.0.0" : "unknown";
+  return typeof __ACTION_VERSION__ !== "undefined" && __ACTION_VERSION__ ? __ACTION_VERSION__ : "unknown";
 }
 function telemetryDisabled(env) {
   const flag = String(env.POSTMAN_ACTIONS_TELEMETRY ?? "").trim().toLowerCase();
@@ -22393,6 +22545,18 @@ function createTelemetryContext(options) {
   };
 }
 
+// src/action-version.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function resolveActionVersion2() {
+  try {
+    const raw = (0, import_node_fs.readFileSync)((0, import_node_path.join)(__dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/index.ts
 var POLL_TIMEOUT_MIN = 10;
 var POLL_TIMEOUT_MAX = 600;
@@ -22458,8 +22622,12 @@ function resolveInputs(env = process.env) {
   const projectName = get("project-name");
   if (!projectName) throw new Error("project-name is required");
   const postmanAccessToken = get("postman-access-token");
-  if (!postmanAccessToken) throw new Error("postman-access-token is required");
   const postmanApiKey = get("postman-api-key");
+  if (!postmanAccessToken && !postmanApiKey) {
+    throw new Error(
+      "postman-access-token is required (or provide a service-account postman-api-key so the action can mint one)."
+    );
+  }
   const postmanTeamId = get("postman-team-id") || env.POSTMAN_TEAM_ID?.trim() || "";
   const workspaceId = get("workspace-id") || env.POSTMAN_WORKSPACE_ID?.trim() || "";
   if (!workspaceId) {
@@ -22699,7 +22867,14 @@ async function runAction() {
   for (const [key, value] of Object.entries(planned)) {
     setOutput(key, value);
   }
-  setSecret(inputs.postmanAccessToken);
+  const mintHolder = {
+    postmanAccessToken: inputs.postmanAccessToken,
+    postmanApiKey: inputs.postmanApiKey,
+    postmanApiBase: inputs.postmanApiBase
+  };
+  await mintAccessTokenIfNeeded(mintHolder, core_exports, (secret) => setSecret(secret));
+  inputs.postmanAccessToken = mintHolder.postmanAccessToken;
+  if (inputs.postmanAccessToken) setSecret(inputs.postmanAccessToken);
   if (inputs.postmanApiKey) setSecret(inputs.postmanApiKey);
   if (inputs.githubToken) setSecret(inputs.githubToken);
   const tokenProvider = createInsightsTokenProvider(inputs, core_exports);
@@ -22716,7 +22891,7 @@ async function runAction() {
     apiBaseUrl: inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE,
     onToken: (token) => setSecret(token)
   }) : tokenProvider;
-  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", logger: core_exports });
+  const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", actionVersion: resolveActionVersion2(), logger: core_exports });
   telemetry.setTeamId(inputs.postmanTeamId || pmakIdentity?.teamId);
   let result;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-insights",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "GitHub Action to onboard Postman Insights discovered services to API Catalog workspaces.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -15,8 +15,9 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --define:__ACTION_VERSION__=\\\"$npm_package_version\\\" --outfile=dist/index.cjs && esbuild src/main.ts --bundle --platform=node --target=node24 --format=cjs --define:__ACTION_VERSION__=\\\"$npm_package_version\\\" --outfile=dist/action.cjs && esbuild src/cli.ts --bundle --platform=node --target=node24 --format=cjs --define:__ACTION_VERSION__=\\\"$npm_package_version\\\" --outfile=dist/cli.cjs",
-    "check:dist": "npm run build && git diff --exit-code -- dist",
+    "prepare": "git config core.hooksPath .githooks",
+    "build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/index.cjs && esbuild src/main.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/action.cjs && esbuild src/cli.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/cli.cjs",
+    "verify:dist": "npm run build && git diff --ignore-space-at-eol --text --exit-code -- dist",
     "docs:tables": "node scripts/render-action-tables.mjs --write",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -46,8 +47,8 @@
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24.12.4",
-    "esbuild": "^0.28.0",
+    "@types/node": "^26.1.0",
+    "esbuild": "0.28.1",
     "eslint": "^10.4.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",