Enterprise best practices: successfully govern your API content and users

There are a ton of things in Postman that enterprises should be taking advantage of to accelerate collaboration and consistency at scale. In this blog post, we’ll go over actionable information and resources related to user management, naming standards, SSO/SCIM, and much more.

Collaborative Postman workspaces enable every person who has access to the workspace to see the same collections, environments, and other assets. This allows for shared-context building that is much faster than traditional modes of collaboration through sending documents over email, and it’s more interactive than traditional portals or docs.

When you provide colleagues and collaborators with better context around your business and stakeholders, you help users make more successful API calls—faster.

Workspace naming conventions

It’s important to name your workspace so that others can understand it without talking to you or sending you an email or additional message.

Have a workspace with the same name as your business unit where you list all the collections and APIs that your team is responsible for. This can be an example workspace that is used as a reference for organizational taxonomy, etc. When designing your taxonomy structure, it’s important to note the hierarchy of elements in the Postman AP Platform:

• Level 1 = Workspace
• Level 2 = Collection, API, etc.
• Level 3 = Additional description for collection, API, etc.

Don’t have multiple workspaces with the same name; this will lead to workspace chaos. Team workspaces should facilitate intentional collaboration.

User Groups

Postman workspaces have User Groups in which team members are organized into functional groups to mimic your organizational structure. This makes it easy to manage and assign roles for all the members of a group.

• Similar to an IDP (Identity Provider) User Group, Admins and Super Admins have capability to create, manage, and delete. Developers can also create, manage, and delete developer-only groups.

Organizing groups to represent the organizational structure of your team is beneficial because it gives every user of your Postman instance the ability to gain context into the departments, teams, and user relationships while editing and collaborating on APIs.

Groups are all about streamlining management over many users and workspaces. If you’re on a team of developers that administer and contribute to a dozen workspaces within Postman, you should not have to add members to every workspace manually.

Roles within a Postman workspace

• Team-level roles: Super Admin, Admin, Billing,  Community Manager, API Network Manager, Partner Manager, Developer and Partner.

• Workspace-level roles: Admin, Editor and Viewer access across the whole workspace.

• Other Postman resources: Editor and viewer access are available across collections, APIs, environments, mock servers and monitors.

Tips when creating collections

• If your collection represents an API functionality, the collection name should summarize the API functionality.
• Naming your environment with known prefixes like “-dev” will make it easier for others to pick the right environment from the dropdown while testing the API.
• Never store sensitive information like keys, request params that represent production traffic (examples: Any PII data like credit cards, addresses etc.; IP addresses of your production servers; sensitive data like the new product your company will be launching etc or any other customer data).

SSO and SCIM

• Once you have SSO set up, you can take your team automation one step further by enabling SCIM. Many organizations may already have an Identity Access Manager set up, simplifying the process of giving the right privileges to the right employees on the right app. Postman can plug right into that provisioning workflow, using the Postman SCIM API, Okta, or Azure AD. Creating, activating, and deactivating a user can be done by team admins, making the process quick and less prone to human error.
• With SCIM enabled, users won’t have the option to leave your team on their own, and they won’t be able to change their account email or password. Only Team Admins will have the right to remove team members.

Domain capture

• Once toggled on and paired with SSO, you can consolidate all of the existing Postman users into one company-managed account that shares your domain. Additionally, you can automatically direct any new users onto the account as well with Just In Time provisioning on the SSO configuration.
• Note that this feature is a little more involved than just a toggle or filling in some fields: since “captured” users will be essentially locked out of their original accounts, it is vital to have a well-communicated plan in place to help everyone prepare and migrate any needed data. Postman’s support and customer success teams are always available to advise and help make the process go as smoothly as possible.

Next steps

By taking advantage of these common approaches to content and user management within your Postman team, you can maintain your instance with a high bar of quality, while ensuring that users get the best experience possible. You may be wondering, what next steps should I take?

• Start with a taxonomy review of your current naming conventions and standards. This can include a subset of the team that can dig into the domain and business to figure out what language will make your team productive and give context.

• Enable users to sign in through an SSO provider if you have one. Additionally, map users from your IDP in groups via SCIM provisioning.

• Make a plan to claim “unclaimed” users that are a part of your domain, but do not exist on your Postman team (they may have their own separate individual teams).
• Start to create and map groups in Postman with your identity provider groups, and create user groups that align with the business outcomes.