User Management API

The API Hub for Design 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.Manage Resource Access

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:

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

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

Authentication

All requests to the User Management API must include the Authorization header containing a API Hub for Design 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

curl "https://api.swaggerhub.com/user-management/v1/orgs/OWNERID/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",
      "email": "alex@example.com",
      "firstName": "string",
      "lastName": "string",
      "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/OWNERID/members?q=alex@example.com

Use the following query parameters to sort and paginate 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. Authenticate the request using the API key of an organization owner or Platform Admin.

This minimal example adds the specified users:

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

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. Authenticate the request using the API key of an organization owner or Platform Admin.

Remove a single user:

curl -X DELETE "https://api.swaggerhub.com/user-management/v1/orgs/OWNERID/members?user=USER@EXAMPLE.COM -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/OWNERID/members?user=USER1@EXAMPLE.COM&user=USER2@EXAMPLE.COM" -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://api.swaggerhub.com/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://api.swaggerhub.com/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "users": [
    {
      "email": "user@example.com",
      "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://api.swaggerhub.com/user-management/v1/orgs/OWNERID/resources/RESOURCENAME/resource-type/API/users' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "users": [
    {
      "email": "user@example.com",
      "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' I will schedule some time for us to connect.\
 'https://api.swaggerhub.com/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://api.swaggerhub.com/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://api.swaggerhub.com/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 then 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://api.swaggerhub.com/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 for the removal of resource access from two teams specified by their names:

curl -X 'DELETE' \
  'https://api.swaggerhub.com/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://api.swaggerhub.com/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://api.swaggerhub.com/user-management/v1/orgs/OWNERID/resource-types' \
  -H 'accept: application/json'

See Also

In this section:
© 2025
Publication date: