User Management API
The API Hub for Design 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.
API reference
A full list of available operations and parameters can be found at:
https://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 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.
Examples
Remove 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 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": "alex@example.com",
"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/OWNERID/members?q=alex@example.com
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
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/OWNERID/members \
-H 'Authorization: OWNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "members": [ \
{ "email": "jack@example.com" }, \
{ "email": "amy@example.com" } \
]}'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/OWNERID/members \
-H 'Authorization: OWNER_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "members": [ \
{ \
"email": "jack@example.com", \
"firstName": "Jack", \
"lastName": "White", \
"role": "DESIGNER" \
}, \
{ \
"email": "amy@example.com", \
"firstName": "Amy", \
"lastName": "Black", \
"role": "OWNER" \
} \
]}'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": "bob@example.com", "role": "DESIGNER" }, \
{ "email": "amy@example.com", "role": "OWNER" } \
]}'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/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"