User Management API

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

Considerations

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

See the full list of available operations and parameters at:

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

Use that page to test API calls directly in your browser.

Base URL

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

http(s)://SERVER/api/user-management/v1/

For example, GET /orgs means a GET request to http(s)://SERVER/api/user-management/v1/.

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 or administrator .

Manage organization members

go.gifGet organization members

go.gifAdd users to the organization

go.gifRemove members from an organization

Get organization members

You can display a list of organization members. To authenticate this request, you must be an organization owner or the On-Premise admin.

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

The response includes first and last names, email addresses, roles, the date and time of last activity, and the last read 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"
      "lastActivePlace": "SWAGGERHUB",
      "status": "ACTIVE"
    },
    ...
  ]
}

Try it out in the interactive API console

Searching and filtering members

Use the q query parameter to search and filter users by their first name, last name, or email address. For example, use it to check if a specific user is already a 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.

To authenticate this request, you must be an organization owner or the On-Premise admin.

This minimal example adds the specified users as Consumers:

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

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. To authenticate this request, you must be an organization owner or the On-Premise admin.

Remove a single user:

curl -X DELETE "https://SERVER/api/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://SERVER/api/user-management/v1/orgs/ORG_NAME/[email protected]&[email protected]" -H "Authorization: OWNER_API_KEY"

Try it out in the interactive API console

Manage resource access

go.gifGet users with access control assigned on the resource

go.gifAssign access control to users on a resource

go.gifUpdate access control for users

go.gifRemove access control for users

go.gifAssign access control to teams on a resource

go.gifGet teams with access control assigned on the resource

go.gifUpdate access control for teams

go.gifRemove access control for teams

go.gifGet all roles assigned to a user in the organization

go.gifGet all resource types and roles that can be assigned

Get users with access control assigned on the resource

You can display a list of users with access to a specified resource.

For example:

curl -X 'GET' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users?statusFilter=all&page=0&pageSize=50' \
  -H 'accept: application/json'

Assign access control to users on a resource

You can grant users access to a specified resource by assigning them a selected role. Authenticate the request with the API key of an organization owner.

For example:

curl -X 'POST' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "users": [
    {
      "email": "[email protected]",
      "role": "designer"
    }
  ]
}' The request must be authenticated using the API key of an organization owner.

Update access control for users

You can update users' access to a specified resource by modifying their role and display the list of users whose access you have updated. Authenticate the request with the API key of an organization owner.

For example:

curl -X 'PATCH' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "users": [
    {
      "email": "[email protected]",
      "role": "designer"
    }
  ]
}'

Remove access control for users

You can remove access to a resource from specific users and display the list of users whose access you have restricted. Authenticate the request with the API key of an organization owner.

The example below allows for the removal of resource access from two users specified by their email addresses:

curl -X 'DELETE' \
 'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users?users=user1%40example.com&users=user2%40example.com' \
 -H 'accept: application/json'

Assign access control to teams on a resource

You can grant teams access to a specified resource by assigning all of their members a selected role. Authenticate the request with the API key of an organization owner.

For example:

curl -X 'POST' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/teams' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "teams": [
    {
      "name": "Example Team",
      "role": "designer"
    }
  ]
}'

Get teams with access control assigned on the resource

You can display a list of teams with access to a specified resource.

For example:

curl -X 'GET' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/teams?page=0&pageSize=50' \
  -H 'accept: application/json'

Update access control for teams

You can update the teams' access to a specified resource by modifying the role of all their members. You will also display the list of teams whose access you have updated. Authenticate the request with the API key of an organization owner.

For example:

curl -X 'PATCH' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/teams' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "teams": [
    {
      "name": "Example Team",
      "role": "designer"
    }
  ]
}'

Remove access control for teams

You can remove access to a resource from specific teams and display the list of teams whose access you have restricted. Authenticate the request with the API key of an organization owner.

The example below allows you to remove resource access from two teams specified by their names

curl -X 'DELETE' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/teams?teams=TEAM1&teams=TEAM2' \
  -H 'accept: application/json'

Get all roles assigned to a user in the organization

You can display a list of all roles assigned to a user in different resources in the organization.

For example:

curl -X 'GET' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/roles?user=user%40example.com&page=0&pageSize=50' \
  -H 'accept: application/json'

Get all resource types and roles that can be assigned

You can display a list of all resource types and the roles you can assign to organization members for each type of resource.

For example:

curl -X 'GET' \
  'https://SERVER/api/user-management/v1/orgs/OWNERID/resource-types' \
  -H 'accept: application/json'

Manage all users (On-prem only)

go.gifList all users

go.gifDelete users from the system

List all users

You can display a list of all users in the system and filter them by username or email address.

For example:

curl -X 'GET' \
  'https://SERVER/api/user-management/v1/users?q=USERNAME&page=1&pageSize=50' \
  -H 'accept: application/json'

Delete users from the system

You can delete selected users from the system. To do that, specify the users by their email addresses. The authenticating user must be the On-Premise admin.

The example below allows you to remove a user with the email address [email protected] from the system.

curl -X 'DELETE' \
  'https://SERVER/api/user-management/v1/users?user=user%40example.com' \
  -H 'accept: application/json'

See Also

In this section:
© 2025
Publication date: