Manage Large Teams in Postman with Workspaces, Permissions, and Version Control

Managing API development with large teams poses a unique set of challenges. Teams need to maintain multiple versions of an API, assign and control ownership and permissions, and smoothly merge new work to a parent API or collection.

Postman provides a set of collaboration features that can help make API development in large teams easier.

In this blog post, I’ll go over the following features so you can simplify collaborating on API development with large teams:

• Workspaces
• Roles and Permissions
• Versioning and Version Tags
• Forking and Merging
• Single Sign-On (Enterprise only)
• Transferring Content

Workspaces

Postman provides personal and team workspaces. Personal workspaces keep your collections and APIs private so only you can work on them. Team workspaces provide visibility to all team members and allow developers to share, comment, and work in parallel on collections – depending on how permissions are assigned for each user.

Roles and permissions

Appropriate access control helps streamline development in large teams and helps team members avoid unwanted changes.

Roles and permissions eliminate the need for owners to control access and instead rely on roles for access control. This shift creates a more automated and reliable workflow and helps avoid losing data when users leave a team.

In a large team, you’ll generally have many different team workspaces and even more shared collections that need to be managed properly.

Postman allows teams to manage workspaces and collections at a granular level to ensure that the correct users have permissions to view or edit APIs and collections.

Below, you can see the roles and permissions flowchart. You can manage teammates on the collection, team, and workspace levels.

Learn more about roles and permissions in our documentation.

Versioning and version tags

Postman’s versioning feature allows you to easily create and maintain multiple versions of an API and tag and maintain multiple versions of the API elements (variables, tests, mock servers, documentation, and monitors) associated with an API version.

This versioning capability makes it easy to view the diff and merge changes so teams can iterate quickly while maintaining a single source of truth.

Version control is particularly powerful within large teams, especially when combined with access control. Setting users as a Collection Viewer still gives them rights to fork a collection and propose changes, but only a Collection Editor will be able to merge them.

Creating API Versions

When you create an API, Postman automatically saves a draft. It’s best to rename your API with a version number before creating another version, so you can easily and numerically organize your versions.

Linking a collection to an API

In order to link a collection to a specific version of an API, you can add documentation or a test suite to the API through the “Develop” or “Test” tabs.

Assigning Version Tags to API Elements

When you create a new version of an API, you can carry over API elements including schema, mock servers, documentation, environments, test suites, contract tests, integration tests, and monitors.

If you’re working in a shared workspace, these versioning features help you and your team organize and maintain multiple versions of your API easily.

To learn more about versioning, read the docs.

Forking and merging

Version control is particularly powerful within large teams, especially when combined with access control. Setting a teammate as a Collection Viewer still gives them rights to fork a collection and propose changes, but only a Collection Editor will be able to merge them.

Postman’s fork and merge feature is similar to that of GitHub, where you can work on the same collection and later merge and pull changes between the forks – keeping collections up to date while enabling developers to work in parallel.

You can fork a collection in a personal or team workspace. In order to create a fork, you must either be a member of a team workspace, or the workspace must belong to you.

Check out our GIF-filled documentation for detailed instructions on forking and merging.

Single sign-on (Enterprise only)

Single Sign-On (SSO) services make it easy to manage your team’s identity across all of the SaaS products that you use.

SSO services allow users to login with one set of credentials (e.g. email and password) to access multiple applications. With only one authentication, users will be given access to all of the applications for which they have permissions.

Enterprise users can create accounts in the Identity Provider (IdP). A user account will be created automatically upon the first login as long as the plan has seats available or if the “Allow Signups” box was checked during SSO configuration. If you do not have seats available, you can add them or get in touch with your CSM.

Visit Postman’s learning center to view our SSO documentation. There are also specific instructions for a number of Identity Providers.

Transferring content

When you set up a new team, chances are that some of the team members may have content they’ve already created in Postman. If this content needs to move with a user to the new team, there are a few scenarios to consider.

If a user has content but has never signed into a Postman account:

If you have been working on Postman collections locally but have never created an account, once you sign in to your new account, the local collections will sync to your Personal Workspace (called “My Workspace” by default). The collections will also sync to the Postman cloud so they are accessible across devices on your account.

If a user has signed into Postman via their own personal account:

If you have a personal Postman account, you can export the relevant content and import the collections and data into the new account. All of your collections and data will remain available on your personal Postman account.

If a user already has an account with the invited email address:

If you have already created an account with the email address used to invite you to the team, all of the collections and data in your account will remain. If you were previously part of a team, you’ll need to export collections from your old team’s workspaces and import them into the new team as described above.

If a user leaves the team:

We recently changed this aspect of Postman in order to ensure that no loss of data would be incurred by teams when users are removed.

Collections are now owned by teams, not the creators of collections. This means that if a user leaves a team, content will not need to be manually transferred, any shared data will persist regardless of who created it. Content will remain whether the collection was shared or directly created in a team workspace.

Using these features, managing a large team can be streamlined. As Postman continues to get adopted by large teams and enterprises, we will continue to add more and more features to support streamlined and secure collaboration and team management.

Watch and learn

Level up your Postman game with our YouTube video that quickly explains how to use version control for Postman Collections with forking, merging, and pull requests: