Skip to main content

​
About Workvivo

Workvivo is Zoom’s employee experience platform - the home for your company intranet, social feed, and internal communications. The Serval Workvivo integration (currently in Beta) connects with an API token: a Workvivo admin pastes a bearer token, your Organisation Id, and your API base URL into Serval. Serval stores the token securely on its servers and attaches your credentials automatically whenever a workflow talks to Workvivo - the token is never exposed to workflow builders or returned to the browser after you save it. Authentication: API token (a bearer token from a Workvivo API app, plus your Organisation Id and API base URL). Data sync: On demand only. Workflows call Workvivo when they run - there is no background data sync, no entity ingestion, and no inbound webhooks. Five scheduled health checks confirm the connection stays valid.

​
What the Workvivo integration enables

CapabilityDescription
Workvivo API request (workflow action)Workflows get typed access to the full Workvivo v1 API - 210 endpoints covering articles, updates, kudos, events, users, chat bots and channels, spaces, pages, teams, notifications, badges, documents, goals, livestreams, and more.
Connection health checksFive scheduled checks continuously verify that your token, Organisation Id, base URL, and permission scopes still work.
AI workflow contextEach connected Workvivo instance is visible to workflows and Serval AI, so even multi-instance setups can target the right Workvivo tenant.
Anything defined in the Workvivo API can be accessed through Serval.

​
Get your credentials

You need three values, all shown on the same screen in Workvivo’s developer admin: a bearer token from a Workvivo API app, your Organisation Id, and your API Base URL. Creating the app requires the Workvivo Developer role. Workvivo’s official walkthrough is here: API Authentication - Bearer Token (see also the Workvivo API Overview and the full APIs help section).
Workvivo warns that Developer-role users can create API apps with up to Admin-level permissions, including actions the normal UI restricts. Grant the role sparingly, and give the Serval app only the scopes it needs.
1

Get the Developer role

Have a Workvivo admin grant your user the Developer role. This unlocks the “API Keys and JWT settings” option in the Workvivo admin panel.
2

Open API Keys and JWT settings

In your Workvivo admin panel, open API Keys and JWT settings (Admin > Developers > Apps). Workvivo tenants live on their own domains, so navigate there from inside your own Workvivo instance.
3

Note your Organisation Id

Your numeric Organisation Id is shown on this screen. This is the “Workvivo-Id (Organisation Id)” value Serval asks for.
4

Create an API app with minimum scopes

Create a new app, name it, and select only the permissions the integration needs. Include the chats.bots.read scope if you want all five Serval health checks to pass. Scopes can be changed later.
5

Generate and copy the token

Click Manage Keys on the app, then Add new Key, and copy the bearer token that populates.
6

Note the API Base URL

Note the Base URL shown when creating the Access Token (Apps > App Settings). It is usually api.workvivo.com, but regional tenants see hosts like api-eu.workvivo.com or api.eu2.workvivo.com. You will enter it in Serval without https:// or a trailing slash.
The token is only shown when the key is created, and the Organisation Id and Base URL appear on the same screens - capture all three values at once.

​
Connect in Serval

1

Open the Workvivo connect form

In Serval, go to your integrations page and choose Workvivo. It is marked Beta in the connect UI, and all three fields are required (marked with an asterisk).
2

Enter the API Base URL

Type the bare host exactly as Workvivo showed it, for example api.workvivo.com - no https://, no path, no trailing slash. The form rejects anything else with “Must be a valid Workvivo API host (e.g. api.workvivo.com or api.eu2.workvivo.com). Do not include https:// or a path.” Leaving it blank shows “This field is required”.
3

Enter the Workvivo-Id (Organisation Id)

Paste your numeric Organisation Id, for example 12345. It is sent with every request Serval makes to Workvivo. Leaving it blank shows “This field is required”.
4

Enter the API Token

Paste the bearer token from Manage Keys. This is a password field and is stored as a secret. On first setup the token is required - if you submit without it, Serval rejects the form with an error that includes “API Token is required”.
5

Submit

Click Submit. The connection appears as “Workvivo ([Organisation Id])”, and Serval’s health checks then run automatically.
When editing an existing connection, the API Base URL and Workvivo-Id come pre-filled with their saved values, and the API Token field appears empty. Leaving the token blank keeps the saved token - so you can change the other fields, or rotate just the token, without re-entering everything.

​
Verifying the connection

Serval runs five scheduled health checks against your Workvivo tenant:
  • Validate Workvivo API Connection - confirms Workvivo accepts your token, Organisation Id, and base URL.
    • Success: “Successfully authenticated with the Workvivo API.”
    • Failure: “Unable to connect to the Workvivo API. Verify the API token, Workvivo-Id header, and base URL are correct.”
  • Check Workvivo Users Read Access - confirms the token can read your user directory.
    • Success: “Successfully listed users ([number] returned)”
    • Failure: “Failed to list Workvivo users. The token may be missing user-read permissions.”
  • Check Workvivo Teams Read Access - confirms the token can read your teams.
    • Success: “Successfully listed teams ([number] returned)”
    • Failure: “Failed to list Workvivo teams. The token may be missing teams-read permissions.”
  • Check Workvivo Spaces Read Access - confirms the token can read your spaces.
    • Success: “Successfully listed spaces ([number] returned)”
    • Failure: “Failed to list Workvivo spaces. The token may be missing spaces-read permissions.”
  • Check Workvivo Chat Bots Read Access - confirms the token has the chats.bots.read scope, which Serval validates ahead of a planned chat capability.
    • Success: “Successfully listed chat bots ([number] returned)”
    • Failure: “Failed to list Workvivo chat bots. The token is likely missing the chats.bots.read scope; chat-source flows will not work until this is granted.”
If your tenant simply has no items of a given type yet, the check still passes with a “Successfully reached the … endpoint” message instead of a count.
The most common partial failure: every check is green except “Check Workvivo Chat Bots Read Access”. That means your API app is missing the chats.bots.read scope. Your workflows and the other checks are unaffected - grant the scope in Workvivo (or accept the single failing check).

​
Gotchas and troubleshooting

The form rejects anything that is not exactly a Workvivo API host: no https://, no path, no trailing slash. If your tenant is regional, use the exact Base URL shown when you created the Access Token - both api-eu.workvivo.com and api.eu2.workvivo.com shapes are accepted, but only workvivo.com API hosts pass Serval’s outbound allow-list. Lookalike domains are rejected.
The Organisation Id (Workvivo-Id), the bearer token, and the Base URL are all surfaced in Workvivo’s developer admin during app and token creation. Capture all three at once - the token is only shown when the key is created.
The “Check Workvivo Chat Bots Read Access” check requires the chats.bots.read scope on your token. If your app lacks that scope, this single check fails while API actions and the other four checks keep working. Grant the scope, or accept the failing check - it exists to validate a future chat capability early.
On the edit form the API Token field appears empty even though a token is saved - Serval never sends the stored token back to the browser. Leaving it blank preserves the stored token, so to rotate it, paste the new value and submit. The base URL and Organisation Id come pre-filled and cannot be saved blank (clearing one shows “This field is required”). Note that changing the Workvivo-Id or base URL changes how the connection is identified and displayed in Serval.
Workvivo’s own documentation warns that the Developer role lets a user create API apps that can be granted up to Admin permissions, including actions the UI normally restricts. Grant the role only to trusted admins, and give the Serval app the minimum scopes it needs.
Workvivo is flagged Beta in the connect UI and is API-actions-only today: no webhooks, no background sync, and it cannot act as a Serval chat source yet. For workflow builders: list results page through with skip and take settings, and list-style filters separate multiple values with the pipe character (for example in_teams=1|2|3).
Need help? Contact support@serval.com for assistance with your Workvivo integration.