Roles
Organization members can have one of the following roles:
-
Owner – has complete administrative access to the organization. Owners can add and delete organization members, manage billing information, fully manage the organization’s APIs and domains. For more information, see Organization Ownership.
-
Designer – can create APIs and domains in the organization and edit those APIs and domains they created themselves. To edit other APIs and domains (created by other members), Designers need to be explicitly added as collaborators to those APIs or domains.
-
Consumer – the default role for new members. Consumers can view the organization’s APIs and domains, but they cannot edit them or create new APIs or domains in the organization.
In SwaggerHub On-Premise 1.19.2 and later, new users who sign up without an invitation are automatically added to the default organization as Consumers.
You can see your role in the header of the organization catalog page:
Permissions
The following table lists the permissions granted by each role. See also Collaborator Permissions for the API- and domain-level permissions that the users get when added as collaborators to individual definitions.
Organization action | Owner | Designer | Consumer |
---|---|---|---|
Members and teams | |||
Add members to and remove them from the organization | ✓ | ||
Create and delete teams | ✓ | ||
See all the organization members and teams | ✓ | ||
Change member roles | ✓ | ||
APIs and domains (in the organization namespace) | |||
View public APIs and domains | ✓ | ✓ | ✓ |
View private APIs | ✓ | ✓ 1 | ✓ 1 |
Create APIs and domains | ✓ | ✓ 2 | |
Edit APIs and domains | ✓ | ✓ 3 | |
Comment on APIs and domains | ✓ | ✓ 4 | ✓ 5 |
Fork the APIs and domains of the organization | ✓ | ✓ | |
Transfer APIs and domains to organization | ✓ | ✓ 2 10 | |
Transfer the organization’s APIs and domains to another owner | ✓ | ✓ 6 10 | |
Configure API Standardization for all APIs in the organization | ✓ | ||
Create custom rules for API standardization | ✓ | ||
View API standardization errors | ✓ | ✓ 7 | |
Add custom branding to documentation | ✓ | ||
Delete APIs and domains | ✓ | ||
Projects | |||
Create, manage and delete projects | ✓ | ||
View projects | ✓ | ✓ 8 | ✓ 8 |
Add APIs and domains to projects | ✓ | ✓ 10 | |
Edit APIs and domains within a project | ✓ | ✓ 3 | |
Remove APIs and domains from projects | ✓ | ||
Billing | |||
View and edit billing information | ✓ | ||
Access billing invoices | ✓ | ||
Miscellaneous | |||
Access the audit log | ✓ | ||
Delete the organization, including all of its APIs and domains | ✓ | ||
Miscellaneous SwaggerHub On-Premise permissions | |||
Create new organizations | ✓ | ✓ | 9 |
1 Designers and Consumers can view private APIs and domains in the following cases:
-
The Allow Designers and Consumers to view all the Organization’s Private APIs option is enabled for the organization.
-
The user is a member of a project that contains private APIs or domains.
2 Only if the Allow Designers to Create APIs under the Organization option is enabled for the organization.
3 Designers only have edit permissions for:
-
APIs and domains they created.
-
Other APIs and domains where they were added as collaborators (either individual collaborators or as part of a team).
Designers do not automatically get edit permissions across the organization or in projects they are member of. Edit permissions are granted when a Designer is added as a collaborator.
4 By default, Designers can only comment on the definitions where they have Edit permissions (see the previous note). In organizations with the Allow Designers and Consumers to Comment option enabled, Designers can also comment on all APIs and domains. This option is available in SwaggerHub SaaS, SwaggerHub On-Premise 1.24 and later.
5 Only if the Allow Designers and Consumers to Comment on all the APIs and Domains they can access option is enabled for the organization. This option is available in SwaggerHub SaaS, SwaggerHub On-Premise 1.24 and later.
6 Only if the Designer has Edit permissions for the API or domain being transferred.
7 Designers can see API standardization errors only in organization-owned APIs they created or have been granted Edit permissions for.
8 Designers and Consumers can only see the projects they are members of.
9 Consumers cannot create organizations unless they have a non-Consumer role in some other organization in your SwaggerHub On-Premise instance.
10 SwaggerHub On-Premise supports this since v. 1.23.
Change member roles via API
Available for organizations on Enterprise and Enterprise Trials plans and for SwaggerHub On-Premise customers.
The User Management API lets you change the roles of one or more organization members in an automated way. The role can be one of the following: "CONSUMER", "DESIGNER", "OWNER". The request must be authenticated using the API key of an organization owner.
Example:
curl -X PATCH https://api.swaggerhub.com/api/user-management/v1/orgs/ORG_NAME/members \
-H 'Authorization: OWNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"members": [ \
{ "email": "bob@example.com", "role": "DESIGNER" }, \
{ "email": "amy@example.com", "role": "OWNER" } \
]}'
See Also
Working With Organizations
Adding and Deleting Users in Organizations
Resource Roles
User Management API