User Management API

Watch the video

The SwaggerHub User Management API can help organizations automate the provisioning of new users. Using this API, you can add and remove organization members and change member roles in bulk.

The API is available for organizations on all plans as well as for both SwaggerHub SaaS and On-Premise customers.

Considerations for On-Premise customers

The User Management API is available in SwaggerHub On-Premise v. 1.26 and later. On-Premise customers should use the bundled API definition located at:

YAML version: http(s)://SERVER/api/user-management/v1/swagger.yaml

JSON version: http(s)://SERVER/api/user-management/v1/swagger.json

You can import this definition as a new API into your On-Premise instance.

API reference

A full list of available operations and parameters can be found at:

go.gifhttps://app.swaggerhub.com/apis-docs/swagger-hub/user-management-api

On that page, you can also test the API calls directly in your browser.

Base URL

The base URLs for requests to the User Management API is:

  • SwaggerHub SaaS: https://api.swaggerhub.com/user-management/v1/

  • SwaggerHub On-Premise: http(s)://SERVER/api/user-management/v1/

For example, GET /orgs means a GET request to https://api.swaggerhub.com/user-management/v1/orgs in SwaggerHub SaaS.

Authentication

All requests to the User Management API must include the Authorization header containing a SwaggerHub API key:

Authorization: YOUR_API_KEY

You can find it on the API Key page in your account settings.

Note

Most requests require the API key of an organization owner.

Examples

The examples below are for SwaggerHub SaaS, but you can adapt them for SwaggerHub On-Premise by replacing the base URL.

go.gifGet organization members

go.gifAdd users to the organization

go.gifChange member roles

go.gifRemove members from an organization

Get organization members

curl "https://api.swaggerhub.com/user-management/v1/orgs/ORG_NAME/members" -H "Authorization: YOUR_API_KEY"

The response includes usernames, email addresses, roles, and the date and time of last activity:

{
  "totalCount": 210,
  "pageSize": 25,
  "page": 0,
  "items": [
    {
      "userId": "b37e1cc6-c32a-4f00-959f-423c180e9fa8",
      "username": "alex",
      "email": "[email protected]",
      "role": "DESIGNER",
      "inviteTime": "2018-07-02T14:32:27.971Z",
      "startTime": "2018-07-02T14:33:56.626Z",
      "lastActive": "2021-11-05T16:41:24.44Z"
    },
    ...
  ]
}

Try it out in the interactive API console

Searching and filtering members

The q query parameter can be used to search and filter users by their username or email address. For example, you can use it to check if a specific user is an existing member:

/orgs/ORG_NAME/[email protected]

Other query parameters can be used to sort and paginate through the user list:

?sortBy=[NAME|EMAIL|START_TIME]&order=[ASC|DESC]

?pageSize=50&page=2     # Default page size is 25

Try it out in the interactive API console

Add users to the organization

You can add one or more organization members by their email addresses and, optionally, set the user roles. The role can be one of the following: "CONSUMER", "DESIGNER", "OWNER". The roles can also be changed later using a separate API call.

The request must be authenticated using the API key of an organization owner.

This minimal example adds the specified users as Consumers:

curl -X POST https://api.swaggerhub.com/user-management/v1/orgs/ORG_NAME/members \
     -H 'Authorization: OWNER_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{ "members": [ \
            { "email": "[email protected]" }, \
            { "email": "[email protected]" } \
         ]}'

Here is an example of the full payload that also sets the user roles and names:

curl -X POST https://api.swaggerhub.com/user-management/v1/orgs/ORG_NAME/members \
     -H 'Authorization: OWNER_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{ "members": [ \
           { \
             "email": "[email protected]", \
             "firstName": "Jack", \
             "lastName": "White", \
             "role": "DESIGNER" \
           }, \
           { \
             "email": "[email protected]", \
             "firstName": "Amy", \
             "lastName": "Black", \
             "role": "OWNER" \
           } \
         ]}'

Try it out in the interactive API console

Change member roles

You can change the roles of one or more organization members in bulk. The role can be one of the following: "CONSUMER", "DESIGNER", "OWNER". The request must be authenticated using the API key of an organization owner.

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": "[email protected]", "role": "DESIGNER" }, \
            { "email": "[email protected]", "role": "OWNER" } \
         ]}'

Try it out in the interactive API console

Remove members from an organization

You can remove one or more users from the organization by their email addresses. The request must be authenticated using the API key of an organization owner.

Remove a single user:

curl -X DELETE "https://api.swaggerhub.com/user-management/v1/orgs/ORG_NAME/[email protected] -H "Authorization: OWNER_API_KEY"

To remove several users, repeat the user query parameter:

curl -X DELETE "https://api.swaggerhub.com/user-management/v1/orgs/ORG_NAME/[email protected]&[email protected]" -H "Authorization: OWNER_API_KEY"

Try it out in the interactive API console

See Also

In this section:
© 2024
Publication date: