Work with Others

This page introduces SwaggerHub's access control and sharing for SaaS and on-prem users. To perform the steps in this tutorial, you need to be an owner of your SwaggerHub account.

Overview

An organization in SwaggerHub is the collection of members (users) and resources that belongs to an account. For all account plans, the organization has an owner (or multiple owners/administrators) who manages users and resource access. For online (SaaS) users, typically only one organization is available. On-Premise installations may have multiple organizations.

Personal plans have only a single user – click here to explore adding users.

Here are the kinds of resource files:

  • API definition files 

  • Domains (shared libraries of API components)

  • API Custom Templates (API definitions that can be used as a basis for new APIs)

  • Portal products

APIs and domains can be grouped into:

  • Projects (folders) or accessed individually.

SwaggerHub allows resources and projects to be shared within your organization. There are roles:

  • Designers have full access to all features of designing and testing API definition files

  • Owners are a special type of designer who can also create/manage users, teams, projects and template files

  • Consumers can review API definition files and optionally comment

For access purposes, users can be grouped into:

  • Teams of members and non-members who work on the same set of resources

roles-in-sh-02-review.jpg

Only the owner/administrator of an organization can:

  • Create organizations (usually only On-Premise accounts have multiple organizations) and modify their settings

  • Add users/members to an organization (issue invitations)

  • Create and manage teams of users

  • Create and manage projects (groups of resources), including access by individual members and teams

  • Create and manage API custom templates

Designers can:

  • Create and update APIs and domains, configure codegen options, generate client and server code

  • Share resources with members and teams (issue invitations)

Consumers can:

  • Review APIs and domains

  • Comment (if allowed)

Collaborators

A special category of user is counted separately in organizations: collaborators. Collaborators are organization members that can only be provided access to individual resources. Collaborators can be either designers or consumers, and they must be invited separately to specific resource files.

Define your organization(s)

Note: An organization was created for you when your account was created. These instructions are only for accounts where multiple organizations are available.

To create an organization, click Create New in the sidebar on the left and select Create New Organization. Specify the Organization Account Name (unique ID), Organization Email, and, optionally, Title.

Create New Organization

Add members to your organization

The next step in working with others is to add users as organization members. To do that, click settings.pngto the right of the organization name.

The created organization

Click the image to enlarge it.

This opens the Organization Settings. Switch to the Members tab to invite users to your organization.

Create teams and add team members

Teams allows you to group members to collectively work on APIs. In any organization, you can create teams on the Teams tab of the Organization Settings screen:

SH_create_teams.png

Click the image to enlarge it.

To learn about organizations and teams in detail, check out our documentation.

Important

When a team is assigned access to a resource, EVERY member of the team is assigned that same access role. So if a team is set to be a designer of a resource, every team member also becomes a designer. If there are insufficient designer license seats available you will not be able to grant the role change to the team. 

We have now successfully created an organization, added members, and added members to teams.

Create projects

Resources in SwaggerHub (API definitions, domains, templates, Portal products) can be grouped into folders, called projects. This is an optional step for organizing your content and managing user access. Projects are displayed on the main screen under the name of your organization.

To create a project, click Create New in the sidebar on the left and select Create New Project. Specify the Project Name (unique ID), and optionally Project Description. You will then have the option of selecting resources and inviting teams/members to your project.

Create resources

To create resources, click Create New in the sidebar on the left and select the type of resource you wish to create -- API, template or domain. The owner must be specified for each type of resource. (Detailed documentation for resource creation is here.)

Only organization owners can create API custom templates. 

Invite members and teams to view/edit your resources and projects

Once a resource is created, from the SwaggerHub editor, owners can add members or teams to work on that resource.

Share an individual resource

In the top right corner of the editor, click share.png>Collaboration to invite members or teams to work with this resource.

Share a project

The projects you have access to are displayed under the organization names in My Hub sidebar.

Projects in SwaggerHub

To invite a member or team to a project, click settings.pngto the right of the project name.

See Also

Publication date: