How to Share Postman Collections with a Team Without Chaos

A shared Postman workspace starts useful and becomes a dump within three months. Someone’s local override leaks into staging, four people have edited the same request, and nobody knows which environment is current.

Direct answer: share Postman collections through team workspaces with role-based access — Editor for engineers, Viewer for QA and PMs — keep environment values out of the cloud, and back up collections as JSON in Git. The free plan includes unlimited collections but only 3 collaborators on shared workspaces.

Which workspace type should you pick?

Three choices, and mixing them is the usual mistake:

Type	Who sees it	Use for
Personal	only you	scratch work, never shared
Team	invited members	one per product or team
Public	anyone with the link	documentation, demos

Use one team workspace per product, not per company. A single company-wide workspace with 400 requests is the thing that becomes unusable. Postman’s search is decent but it cannot fix unclear naming.

Paid plans add Partner and Private workspaces with finer controls. On the free tier the 3-collaborator limit on shared workspaces is the real constraint — a fourth person gets view-only.

How should the collection be organised?

Folders first, then naming conventions.

• Auth/ — token, refresh, revoke.
• Users/ — CRUD requests.
• AI/ — the model calls, kept apart because they are slow and costly.
• _smoke/ — the five requests that must pass before a deploy.

Name requests as verb plus resource: Create user, List invoices. Not test1, not new request copy 3. Six months from now the names are the only documentation.

Keep the smoke folder small enough to run in under 20 seconds. A smoke run that takes two minutes stops being run.

Is exporting to Git worth the friction?

Usually yes, and here is the trade-off. Editing in the cloud is convenient and gives instant sync, but you lose pull-request review, and a bad edit propagates to everyone before anyone notices.

The workflow that works: edit in Postman, export collection JSON, commit with a message, let the PR get reviewed. Postman has a Git integration on paid plans that does this natively; on the free tier you export manually or use the API.

newman run collection.json --environment env.json --folder _smoke

Because the collection is a JSON file, a diff shows exactly which URL or assertion changed. That review is worth the export step for anything touching payment or auth.

How do you stop environment leaks?

Three rules that prevent most incidents:

1. Never commit an environment file with values in it. Export with Current values unchecked.

2. Prefix environment names by target: prod, staging, local.

3. Make production a Viewer-only workspace so nobody can accidentally run a destructive request against it.

The third one is not paranoia. DELETE /v1/customers/{{id}} with a stale id from staging, run against production because the active environment was wrong, is a documented failure mode at more than one company.

Postman shows the active environment in the top-right, and it is easy to miss. Set the production environment’s colour to red in its settings if you must have it open.

What are collection variables for, then?

Values generated during a run: a created resource ID, an auth token, a pagination cursor. They live in the collection and disappear when the run ends.

Environment variables are for configuration that outlives a run. Collection variables are for state within a run. Putting a baseUrl in collection variables means every fork of the collection carries its own copy, and forks drift.

What about the free tier limits?

The practical ones:

• 3 collaborators on a shared workspace.
• 1,000 mock server calls per month.
• 25 collection runs per month on the cloud runner.
• 1,000 requests per month to the Postman API.

25 cloud runs is one per working day. If you want a nightly CI run, use Newman locally in your pipeline instead — it has no such cap and costs nothing.

Where this breaks down

Postman is not a spec. If your API contract matters to other teams, an OpenAPI file is the source of truth and the collection is a client of it. Maintaining both by hand guarantees they diverge.

And for a team of two who both use the terminal, curl scripts in a scripts/ folder plus a Makefile is less setup for the same result. Postman earns its place when non-engineers need to run requests — that is the actual feature.

Key Takeaways

• One team workspace per product; company-wide workspaces become unsearchable.
• Free tier caps shared workspaces at 3 collaborators and 25 cloud runs per month.
• Export collection JSON to Git for review; a JSON diff shows exactly what changed.
• Keep production viewer-only and never export environment values.
• Postman complements OpenAPI, it does not replace it.