The Viva Engage team is consistently working to prioritize customer requests, so we're excited to introduce Viva Engage Role Management APIs now available in Microsoft Graph Beta: Use the Microsoft Graph API to work with Viva Engage (preview).
These APIs will help admins and those with appropriate non-admin privileges to automate the role assignments, reading, assigning, and demoting users from a specific Viva Engage role not defined in Entra. Other Viva Engage roles such as Yammer administrator and Knowledge Managers were already supported in Microsoft Graph API via Entra.
The new APIs will be supported via app-delegated (user auth) and app-only access. Feel free to try out these APIs and reach out to us with your feedback. See Microsoft Graph REST API beta endpoint reference to learn more about the MS Graph beta program and best ways to provide feedback.
The prerequisites for testing these APIs are:
- Admin access to run APIs using Graph Explorer
- Some APIs require tenant admin approval.
- Ensure to use the correct role id for assignment. The role ids supported by these APIs are:
- Corporate Communicator: 77aa47ad-96fe-4ecc-8024-fd1ac5e28f17
- Network Administrator: ec759127-089f-4f91-8dfc-03a30b51cb38
- Verified Administrator: 966b8ec4-6457-4f22-bd3c-5a2520e98f4a
- Please make sure to read through the Use the Microsoft Graph API to work with Viva Engage (preview)guide before you begin
Read Viva Engage admin/non-admin roles via role management API
To start with the testing of these APIs, please follow the steps below.
Register a new app in Azure Active Directory (Entra)
- Go to Register an application - Microsoft Azureand register a new application.
- Specify your custom callback url.
Select tokens to be issued by authorization endpoint
Click on ‘Authentication’ tab -> Check ‘Access tokens’ and ‘ID tokens’ -> Click save
Request API Permissions
- Go to ‘API permissions’ tab -> Click on ‘Add a permission’ -> Select ‘Microsoft Graph’
- Choose ‘Delegated permissions’ if testing the API with your own credentials. Choose ‘Application permissions’ if you wish to use app-only access, without a signed in user.
- Choose between Read.All or ReadWrite.All permissions. Role assignment/creation requires EngagementRole.ReadWrite.All permission, but if you only want to test the roles read operation, less privileged access EngagementRole.Read.All should be used:
- Before your app can use these permissions, an admin must approve them. Share your app’s API permission url with a tenant admin, and ask them to grant admin consent:
- After admin consent is granted, you will see it as shown below.
Create Role Management POST request url & body
- Login to Graph Explorer and get required permissions to test the APIs.
- Set up the Add a user as a corporate communicator POST request on Graph Explorer.
- Set, Request type: POST and Request URL: https://graph.microsoft.com/beta/employeeExperience/roles/{engagementRoleId}/members
- Click on ‘Request Body’ tab & provide required parameter.
https://graph.microsoft.com/beta/users(‘targetUserEntraId’)
o TIP: To find Entra id of the target user to be added a role, visit Users - Microsoft Azure portal and click on the specific user you are looking for. Copy the ‘Object id’
- Send request. If the request is submitted successfully, a ‘204 No Content response will be returned.
Read the assigned roles for a role Id/role type
Use a new Graph Explorer tab to poll for created role status:
- Set Request Type: GET and Request URL: https://graph.microsoft.com/beta/employeeExperience/roles/{engagementRoleId} /members
- Send request. Once, role assignment is complete, the API will return a ‘200 OK’ response, with a list of users with a specific Viva Engage role.
Read role assigned to the logged in user
Use a new Graph Explorer tab to read your assigned roles:
- Set Request Type = GET & Request URL = https://graph.microsoft.com/beta/me/employeeExperience/assignedRoles
- Upon success, a ‘200 OK’ response is returned along with Response body containing Role id and name.
To check the roles assignment for various roles, feel free to look up the assigned roles on Viva Engage Admin Center.
Microsoft