Skip to main content

​
About Envoy

Envoy is a workplace and visitor management platform covering locations, employees, visitor invites, entries, and sign-in flows. Serval connects to Envoy’s v1 REST API using an Envoy Client API Key, letting workflows list locations and sign-in flows, retrieve visitor invites, create new visitor invitations, and reach anything else in the Envoy API through a generic request action. Serval only ever talks to Envoy’s official API address (api.envoy.com), so workflows cannot use this connection to call any other service. Authentication: API key (Envoy Client API Key), sent with every request Serval makes on your behalf. Data sync: On-demand only. Workflows call Envoy when they run, and two health checks verify connectivity. Nothing is imported into Serval automatically, and there is no background sync or webhook ingestion.

​
What the Envoy integration enables

Anything defined in the Envoy API can be accessed through Serval.

​
Get your credentials

Serval authenticates with a Client API Key, which Envoy issues when you create an integration in the Envoy Dev Dashboard. See the Envoy developer documentation for background.
1

Create a dedicated API user (recommended)

In the Envoy employee directory, click Add Employee and create a dedicated API user with a service-account email address. Assign it the Global Admin role and disable Show employee as a host on the Visitors Kiosk.
2

Create a new integration

Sign in as the dedicated API user from the previous step, then open the Envoy Dev Dashboard and click Create New. Performing this and the following steps as that user means the integration and its Client API Key are owned by a stable service account rather than a personal account.
3

Name the integration

Give it a name (for example, “Serval Integration”) and a short description.
4

Select API scopes

At minimum, grant read access to companies and locations. Add invite, visitor, and employee scopes if you plan to use the invite workflows.
5

Save

Check Is the integration ready to be displayed? and click Save.
6

Copy the Client API Key

Expand the Envoy API Credentials section on the same page, locate the Client API Key, and copy it for the Serval connect form.
Do not skip the scopes step. Serval’s connection health checks read your company and location lists, so a key without those read scopes fails its health checks even if other calls work.

​
Connect in Serval

1

Open the Envoy connect form

In Serval, add a new Envoy connection.
2

Enter an Instance Name

Instance Name (required) is a friendly name to identify this integration instance inside Serval. Leaving it blank shows “This field is required”.
3

Paste your API Key

API Key (required) is a password field with the helper text “Your Envoy API key (Client API Key)”. Paste the Client API Key you copied from the Envoy Dev Dashboard. Leaving it blank shows “This field is required”.
4

Save the connection

Submit the form. The key is stored encrypted, and afterward it displays as bullets plus its last 4 characters. If saving fails, you may see “Failed to install integration” or “Failed to save configuration. Please try again.”
Saving the form does not test your key against Envoy. A successful save only means the key was stored - run the health checks right after connecting to confirm it works.
When editing an existing Envoy connection, the saved key appears in a disabled, obfuscated field with a Replace button (clicking it shows a password input with the placeholder “Enter new value”). Whenever you save the configure form again - even if you only changed the Instance Name - click Replace and paste the full API key before saving. Do not save with the key field left untouched or cleared.

​
Verifying the connection

The Envoy integration ships with two health checks:
  • Test Envoy List Companies confirms Serval can reach Envoy with your stored key by reading your company list. Success shows “Successfully connected to Envoy and retrieved companies list”; failure shows “Failed to connect to Envoy or list companies. Please check your API key and permissions.”
  • Test Envoy List Locations does the same by reading your location list. Success shows “Successfully connected to Envoy and retrieved locations list”; failure shows “Failed to connect to Envoy or list locations. Please check your API key and permissions.”
Health checks green but the invite workflows fail? The checks only prove company and location read access. Go back to your integration in the Envoy Dev Dashboard and add invite, visitor, and employee scopes.

​
Gotchas and troubleshooting

Always re-enter the API key when you save the configure form for an existing connection, even for an unrelated change like renaming the instance: click Replace and paste the full key, then save. If the connection starts failing immediately after an edit, re-enter the key to restore it.
The connect form saves without contacting Envoy, so a wrong or under-scoped key still reports a successful connection. Run the health checks (or the Get Envoy Locations starter workflow) right after connecting to confirm the key actually works.
Both health checks read your company and location lists directly from Envoy. If the integration you created in the Envoy Dev Dashboard lacks scopes that permit reading companies and locations, health checks fail even when other scoped calls work. Add those read scopes to the integration in Envoy.
The Envoy API request action automatically adds the v1 version prefix to any path that does not already start with it, so you can enter the path with or without the prefix. Do not write the prefix twice - the action does not strip duplicates, so a doubled version path fails. Always start the path with a forward slash: the prefix is joined directly onto whatever you enter, so a missing slash produces a malformed address. Only Envoy’s API host is reachable through this connection, and any record IDs must be written directly into the path itself; there is no separate path-parameters input.
That is expected. After connecting, the form shows the key as bullets plus its last 4 characters, and the stored value is encrypted. Use those trailing characters to confirm which key is saved before rotating or replacing it.
Need help? Contact support@serval.com for assistance with your Envoy integration.