A leaked Postman API key is rarely the whole problem: it reaches every collection and environment its owner can see, and those are where teams keep the API keys, bearer tokens and passwords for everything else they test. Postman credentials therefore behave like a key to a second-tier secrets store that was never designed as one. This guide covers the two Postman credential types (personal API keys and collection access keys), how to recognise them, how Postman's own Secret Scanner and GitHub's partner programme react to exposure, what Postman's audit logs show, and the revoke, rotate and clean-up steps from Postman's documentation. It is written for API, platform and AppSec teams who run Postman at team or enterprise scale. Read the Leaked Credential Response Playbook for the general process; this page adds the Postman specifics.
Key takeaways
- A Postman API key acts as its owner. Postman states that a key provides access to any Postman data its owner has permissions for, across workspaces, through the Postman API and Postman CLI.
- The blast radius is the secrets inside Postman. Treat every third-party credential stored as a shared variable value in a reachable workspace as exposed when a Postman key leaks.
- Two credential types, both detectable. Personal keys begin
PMAK-; collection access keys grant read-only access to one shared collection. GitHub scans for both, including in public repositories, with validity checks. - Public workspace secrets are auto-masked, not revoked. Postman replaces secrets found in public workspaces with placeholders, but the real values may already have been copied: rotate them at the issuer.
- Local values and Vault reduce exposure. Values kept local or in Postman Vault do not sync to Postman Cloud, so a stolen API key cannot read them.
How identity and access work in Postman
People sign in to Postman with their own accounts. Automation uses the Postman API, which authenticates with an API key sent in the X-API-Key header. Postman's documentation describes two credential kinds:
| Credential | How to recognise it | What it reaches | Where it is managed | Lifetime |
|---|---|---|---|---|
| Postman API key (personal) | Begins PMAK-, sent as X-API-Key; often stored in a variable named postman-api-key | Any Postman data the owner has permissions for, such as workspaces, collections and environments, through the Postman API and CLI | Settings, Account settings, API keys; Enterprise Admins also use the API key management dashboard | Expiry period set under API key settings; admins can lock these settings |
| Collection access key | Part of a collection shared through the Postman API; GitHub secret type postman_collection_key | Read-only access to one collection, including any values saved in it | Listed under Collection access keys on the API keys page, with collection, creator and creation date | Until deleted; a new one is generated each time a collection is shared through the API |
The data model matters as much as the key. Collection, environment and global variables each have a local value, which stays on the user's machine, and an optional shared value, which syncs to Postman Cloud and is visible to anyone with access to that element. Monitors, scheduled runs and the Postman CLI use the shared value, so teams that run collections in the cloud tend to put real credentials in shared values. Postman Vault adds a Local Vault (encrypted, not synced, all plans) and a Shared Vault (encrypted in Postman Cloud at workspace level, on Solo, Team and Enterprise plans).
| Where a third-party secret sits | Readable with a stolen Postman API key? | Readable from a public workspace? |
|---|---|---|
| Shared value of a collection, environment or global variable | Yes, if the key owner can access the element | Yes, if the workspace is public |
| Hard-coded in a request header, body or script | Yes | Yes |
| Local value only | No (not synced) | No |
| Local Vault or a linked external vault | No (not synced) | No |
| Published documentation with saved examples | Yes | Yes, publicly |
See the API Key Management Guide for the lifecycle model behind personal keys.
Admin roles and privileged access
- Team Admins and Super Admins: on Enterprise plans they manage the Secret Scanner dashboard, set Local Secret Protection policies per workspace and open Team, Audit Logs. Their API keys reach the widest set of workspaces, so treat them as privileged credentials.
- Enterprise Admins: manage team members' API keys at scale in the API key management dashboard and can stop users changing key settings such as expiry.
- Workspace Admins: receive Secret Scanner notifications for their workspaces and can retrieve findings through the Postman API with Admins and Super Admins.
- Editors: need Editor access to set a shared value, which is the action that moves a secret into Postman Cloud. Limit Editor rights on workspaces that hold production credentials.
Workspace visibility is the other privileged setting. A workspace switched to public publishes every shared value, request and saved example in it. Restrict who can create or change public workspaces, and review public workspaces owned by your team regularly. The SaaS Security Guide covers the same sharing problem across other tools.
Integrations, API tokens and service accounts
Choosing how to hold credentials
| Need | Prefer | Avoid |
|---|---|---|
| CI pipeline running collections with the Postman CLI | A dedicated Postman account for CI, API key with an expiry, injected from the CI secret store | A developer's personal key in pipeline YAML |
| Target API credentials for monitors and scheduled runs | Shared Vault, or an external vault link on Enterprise (1Password, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) | Production tokens in shared environment values |
| Developer testing | Local values and Local Vault, non-production credentials | Pasting production tokens into request headers |
| Sharing a collection with a partner | A Partner Workspace or sanitised copy, with collection access keys deleted when the engagement ends | A public workspace with working credentials |
A dedicated CI account means a key leak is limited to what CI needs, and the key survives staff changes. Because a Postman API key acts with its owner's permissions, never run automation on the key of an admin. The SaaS API Token Security Guide discusses the same personal-token problem in other SaaS platforms.
Logging and detection
Detection coverage
| Detector | Covers | Action on a finding |
|---|---|---|
GitHub secret scanning, postman_api_key | Public repositories (partner programme) and private repositories with GitHub Advanced Security; push protection and validity check | For a valid key in a public GitHub or GitLab repository, Postman notifies the key owner by email and in-app |
GitHub secret scanning, postman_collection_key | As above, with validity check | Alert to repository admins; delete the collection access key |
| Postman Cloud Secret Detection | Public workspaces by default; internal and Partner Workspaces with the Advanced Security Administration add-on; collections, environments and published documentation | In public workspaces, secrets are replaced with placeholders such as {{authorization-secret}}; Admins and Workspace Admins are notified |
| Postman Local Secret Protection | All workspace types before data syncs, including connected Git projects | User chooses Vault, plaintext or removal, per workspace policy |
| Gitleaks default rules | postman-api-token rule keyed on PMAK- | Your pipeline's policy |
Two caveats from Postman's own documentation: non-HTTP requests are not auto-replaced and must be cleaned by hand, and masking a secret in Postman does nothing at the issuing service. Postman's advice is to revoke exposed secrets and replace them. See the Git Secret Scanning Guide for scanner tuning.
Audit logs
On Enterprise plans, Postman keeps audit logs for 180 days. Admins and Super Admins view them under Team, Audit Logs, filter by date range, event type and team member, and export CSV through an emailed link valid for one hour (an unfiltered export covers only the last seven days). The audit logs API feeds a SIEM, and GET /audit-actions lists every event type. Each event records the actor's name, email and IP address, the event type, a timestamp and, through the API, the user agent. Documented examples include sign-ins, creating a Postman API key and adding a team member. Because retention is 180 days, export to your own log store if your investigations look back further. See the SaaS Audit Log Retention and Licensing Guide.
What to alert on
- Postman API key creation outside your CI account and named owners.
- Actions from a known key owner's account at IP addresses or user agents that do not match their normal tooling.
- Workspaces changed to public, and Secret Scanner findings in any workspace.
- A GitHub
postman_api_keyalert with validity status active.
Metrics
- Open Cloud Secret Detection findings, and median time to close.
- Share of secrets held in Vault versus shared values (Postman's add-on reports track moves to Vault and policy overrides).
- Number of public workspaces owned by the team, with a named owner for each.
- API keys without expiry, and keys older than your rotation period.
- Collection access keys older than 90 days.
Leak response: revoke and rotate
- Identify the key: a
PMAK-value is a personal API key; find its owner through GitHub's alert, the API key management dashboard or by asking the team. A collection access key points to one shared collection. - Kill the Postman credential: the owner opens Settings, Account settings, API keys and deletes or regenerates the key from its more-actions menu; on Enterprise, an admin can act from the API key management dashboard. For a collection access key, hover over it under Collection access keys and click Delete.
- Replace it safely: issue a new key with an expiry, store it in the CI or local secret store, and confirm pipelines and Postman CLI jobs run.
- Scope the second-order exposure: list every workspace, collection and environment the owner could reach. Every third-party secret in a shared value, request, script or saved example there must be treated as exposed and rotated at its issuer, starting with production cloud, payment and identity provider credentials.
- Review activity: filter audit logs by the key owner from the earliest possible exposure, looking for unfamiliar IP addresses, new keys, members added and workspace changes. Check issuer-side logs for the third-party secrets too.
- Clean the source: remove the key from the repository, history, CI logs and images; for public workspace findings, also handle non-HTTP requests by hand.
- Record and fix the root cause: move the rotated third-party secrets into Vault or local values so the next key leak exposes less. The Secrets Rotation Runbook Template gives the evidence fields.
Hardening baseline
- Find the secrets first: run Cloud Secret Detection across all workspaces (internal workspaces need the add-on) or export collections and environments and scan them with your own tooling.
- Move secrets out of shared values: pilot with one team, moving credentials into Shared Vault or an external vault link, then confirm monitors and scheduled runs still work before rolling out.
- Turn on Local Secret Protection: start in the least restrictive policy on a pilot workspace, review overrides in the reports, then tighten.
- Set and lock key expiry: configure API key expiration and prevent users from changing it.
- Govern public workspaces: limit who can publish, review existing public workspaces and remove working credentials from anything public.
- Separate automation identities: create a CI account per pipeline family with only the workspaces it needs.
- Roll back if needed: if a Vault migration breaks a monitor, restore the previous shared value temporarily, rotate it afterwards, and fix the reference.
Small teams without Enterprise features can still use Local and Shared Vault, keep production credentials out of shared values, set key expiry and scan exports with an open source scanner. Larger organisations should use the Secret Scanner dashboard and findings API, external vault links and SIEM ingestion of audit logs.
Common misconfigurations
- Production tokens in shared environment values: one Postman key, or one public workspace, then exposes them.
- Personal keys of admins in CI: a pipeline leak becomes a team-wide data leak.
- Trusting placeholder replacement: masking in a public workspace does not invalidate the original secret.
- Forgotten collection access keys: each API share creates a new key, and old ones stay valid until deleted.
- Short log retention: 180 days of audit logs is not enough for long-tail leaks unless exported.
- Keys without expiry: leaked keys stay useful indefinitely.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | ISO/IEC 27001:2022 Annex A | MITRE ATT&CK |
|---|---|---|---|---|
| Key ownership, expiry and removal | IA-5, AC-2 | PR.AA-01 | A.5.17 Authentication information | T1078.004 Cloud Accounts |
| No secrets in collections, code or exports | IA-5(7) | PR.DS-01 | A.8.4 Access to source code | T1552.001 Credentials In Files |
| Workspace access and public sharing | AC-6, AC-3 | PR.AA-05 | A.5.15 Access control | T1213 Data from Information Repositories |
| Audit log review and secret findings | AU-6, SI-4 | DE.CM-09 | A.8.16 Monitoring activities | T1528 Steal Application Access Token |
Practitioner checklist
- Inventory API keys and collection access keys, with an owner for each.
- Run a dedicated Postman account for CI and remove admin keys from automation.
- Set and lock API key expiry.
- Move production credentials from shared values into Vault or an external vault.
- Enable Cloud Secret Detection and Local Secret Protection where your plan allows.
- Review public workspaces and restrict who can publish.
- Export audit logs to your SIEM to keep more than 180 days.
- In any Postman key leak, rotate the third-party secrets the key could read, not only the key.
Standards and references
- Postman: Generate and use Postman API keys
- Postman: Secret Scanner
- Postman: How Secret Scanner works
- Postman: Audit logs
- Postman: Postman Vault
- Postman: Store and reuse values using variables
- GitHub Docs: Supported secret scanning patterns
- NIST: SP 800-53 Rev 5, Security and Privacy Controls
Related NHI Mgmt Group resources: Leaked Credential Response Playbook · API Security Guide · Secret Sprawl Measurement Guide · Secrets Management Guide