About the Users API

The Users API enables account owners to manage their account's team members access to account assets. Through this API, you can access team member data and roles, including open invites, and assign and unassign team member roles to each asset, ensuring that each team member has the appropriate level of access to the different assets within the account.

Important:

This API manages team members within accounts, and is not intended for managing customer access to individual sites.

Use cases

Terminology

  • Assignment: The mapping of a Wix user's access to an asset and their assigned role. For example, Sally has access to the XYZ site owned by Jennifer with a website manager role, and Alice has access to Selena’s Wix account with a co-owner role.
  • Facet: A type of filter that divides items into logical subdivisions, and counts the number of items in each. See Filters and Facets: An Explainer for more information.
  • Policy: See Role below.
  • Restriction: The asset a user is assigned access to in an assignment, including any restrictions to their access.
  • Role: A defined type of access that an identity should have on a specific site or account. Wix provides several predefined roles, such as co-owner, website manager, and website designer (see the full list of available predefined roles). Account owners and co-owners can also define their own custom roles.
  • Subject: The identity assigned to the asset in an assignment. Supported subjects include user IDs, account IDs, and app IDs.
  • Team: The group of Wix users that are team members of an account.
  • Team member: A Wix user that has been added to an account, with access to one or more sites and other assets. One Wix user can be a team member of multiple accounts.
  • User: A logged in user on *.wix.com.
Did this help?

Sample Flows

This article shares some typical use cases you can support, as well as an example flow that supports each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.

Periodically check and update company employees' account access

If your company has a Wix account with employees as team members, you may want to periodically check the access that each team member has to your account assets and the roles they have for each site.

  1. Call Search Team with any relevant filters.
  2. Review the returned lists of users and invites, and their assignments.
  3. If relevant, call Get Roles Info with any relevant filters, to retrieve a list of all roles that can be applied to your account's team members.
  4. If changes should be made to any team member's roles or access to account assets, call Update Team Member Assignments.
  5. If an employee leaves, or should have their access removed for any reason, call Remove Member.
Did this help?

User Object


Properties
idstring

User ID.


rolesArray <string>deprecated

Deprecated.


emailstring

User's email address.


nameName

User's name.


profileImagestring

URL to user's profile image, when provided.


joinedTeamAtstringformat date-time

Date the user joined the team.


policyIdsArray <string>deprecated

Deprecated.


assignmentsArray <Assignment>

Resources the user can access.

Did this help?

POST

Remove Member


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Removes a team member from the requesting account.

Important: This call requires an account level API key and cannot be authenticated with the standard authorization header. API keys are currently available to selected beta users only.

Endpoint
POST
https://www.wixapis.com/roles-management/team/remove

Body Params
userIdstringRequired

User ID of the team member to remove.

Response Object
Returns an empty object.
Remove team member for account
Request
cURL
curl -X POST \ 'https://www.wixapis.com/roles-management/team/remove' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "userId": "fed9597b-00a1-4bd6-0000-aff2ec248e7a" }'
Response
JSON
{}
Did this help?

POST

Search Team


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves all team members of the requesting account, based on the provided filters and free text queries.

Important: This call requires an account level API key and cannot be authenticated with the standard authorization header. API keys are currently available to selected beta users only.

Endpoint
POST
https://www.wixapis.com/roles-management/v3/team/search

Body Params
querystring

Free text to search for within team member name and email address fields.


orderByArray <Ordering>

Sort data.


filterstruct

Filter object. Supported values: inviteType and roleId. For example, {'inviteType': {'$eq': 'Expired'}}. See API Query Language for more information.


facetsArray <string>

A list of facets to return in the response. Facets count the items within logical groupings. See Filters and Facets: An Explainer for more information.


pagingPaging

Pagination.

Response Object
facetsArray <Facet>

List of facets, as requested.


teamMembersArray <TeamMemberV3>

Existing team members and invites sent to join the account.

Search for team members by filters
Request
cURL
curl -X POST \ 'https://www.wixapis.com/roles-management/v3/team/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "filter": { "roleId": "6600344420111308827" } }'
Response
JSON
{ "teamMembers": [ { "user": { "id": "fed9597b-7e80-ba1b-b666-add246249e70", "email": "test@email.com", "name": { "firstName": "Foo", "lastName": "Bar" }, "joinedTeamAt": "2017-01-23T10:13:42Z", "assignments": [ { "policyId": "6600344420111308827", "assignmentId": "7167886595789334551", "subject": { "id": "fed9597b-7e80-ba1b-b666-add246249e70", "subjectType": "USER" } }, { "policyId": "6600343671872641041", "assignmentId": "6684420183164737859", "restrictions": { "site": { "id": "867496aa-40bc-4aff-b2fc-7a5e88fbe06c", "value": "xfgdfgd" } }, "subject": { "id": "fed9597b-7e80-ba1b-b666-add246249e70", "subjectType": "USER" } } ] } }, { "invite": { "id": "bfb00082-28bd-4da9-b234-9c60e6b821ed", "email": "some@email.com", "acceptLink": "https://manage.wix.com/team/accept?inviteToken=JWS.eyJraWQiOiJyLUoxaGtociIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoie1wiaW52aXRlSWRcIjpcImJmYjAwMDgyLTI4YmQtNGRhOS1iMjM0LTljNjBlNmI4MjFlZFwiLFwicmVzb3VyY2VJZFwiOlwiZmVkOTU5N2ItM2Q5Zi00Y2MyLWI5MTMtYWZmMmVjMjQ5ZTdhXCJ9IiwiaWF0IjoxNzMxMzI3MzE5fQ.A9zoljQOdoLeEsKizf1vPAeLhrJ7Mte2ZCZd-h4QGh4", "dateCreated": "2024-11-11T12:15:18Z", "dateUpdated": "2024-11-11T12:15:18Z", "assignments": [ { "policyId": "6600344420111308827" } ], "expirationDate": "2024-12-11T10:15:18Z" } }
Did this help?

GET

Get Roles Info


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves all available roles in the requesting account, including predefined and custom roles.

Important: This call requires an account level API key and cannot be authenticated with the standard authorization header. API keys are currently available to selected beta users only.

Endpoint
GET
https://www.wixapis.com/roles-management/roles

Query Params
localestring

Language of predefined roles names and descriptions to return, in ISO 639 format. Default: en.


filter.roleLevelstring

Role level to return. Default: ALL.


filter.editorTypesArray <string>

Filter for editor-specific roles. Default: ALL.

Response Object
predefinedRolesArray <RoleInfo>

Predefined roles.


customRolesArray <RoleInfo>

Custom roles.

Get Roles Info
Request
cURL
curl -X GET \ 'https://www.wixapis.com/roles-management/roles' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "filter": { "roleId": "6600344420111308827" } }'
Response
JSON
{ "predefinedRoles": [ { "id": "6601492336091027458", "title": "Owner", "description": "Can manage and access all aspects of sites, including billing and domains, plus invite other people and set their permissions." }, { "id": "6642345101181663232", "title": "Account Admin (Co-Owner)", "description": "Can manage and edit all sites and apps in the account, including billing, domains and inviting people, but cannot close account.", "restrictFromLevel": "Site" }, { "id": "6732588207941061632", "title": "Admin (Co-Owner)", "description": "Has access to edit, publish and manage site, including billing, payment & financial info, domains and inviting people, but can't delete or transfer the site.", "restrictFromLevel": "Account" } ], "customRoles": [ { "id": "7046409866117489206", "title": "This is a custom role test", "description": "This is a custom role test" }, { "id": "7231566973429198887", "title": "Another custom role" } ] }
Did this help?

PATCH

Update Team Member Assignments


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates the assignments of roles and conditions for an existing team member. Changing assignments changes the team member’s access to account assets.

Important: This call requires an account level API key and cannot be authenticated with the standard authorization header. API keys are currently available to selected beta users only.

Endpoint
PATCH
https://www.wixapis.com/roles-management/v2/team/assignments

Body Params
userIdstringRequiredformat GUID

ID of team member being affected.


newAssignmentsArray <AssignmentV3>RequiredmaxItems 50

New assignments to apply to the team member in this account.


assignmentIdsToRemoveArray <string>Requiredformat GUIDmaxItems 50

Existing assignment IDs to remove. To retrieve all existing assignment IDs for a team member, call Search Team.

Response Object
assignmentsArray <AssignmentV3>

The new assignments, assigned to the given team member.

Update assignments
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/roles-management/v2/team/assignments' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "userId": "fed9597b-00a1-4bd6-0000-aff2ec248e7a", "newAssignments": [ { "policyId": "6600344420111308827" } ], "assignmentIdsToRemove": [ "7167886595789334551" ] }'
Response
JSON
{ "assignments": [ { "policyId": "6600344420111308827", "assignmentId": "7167886595789334588", "subject": { "id": "fed9597b-00a1-4bd6-0000-aff2ec248e7a", "subjectType": "USER" } } ] }
Did this help?