> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/envoy.md).

# Envoy

Register visitors, look up locations and employees, and reserve desks in Envoy's workplace platform.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector       | Authentication |
| --------------- | -------------- |
| Envoy (OAuth2)  | OAuth sign-in  |
| Envoy (API Key) | Client API Key |

#### Envoy (OAuth2)

Sign in with Envoy to register visitors, look up locations and employees, and reserve desks.

**Set up in Envoy**

1. In the Envoy Dev Dashboard, create or select an unlisted app. Configure it to install Externally using OAuth2.
2. Add the StackAI callback URL as a redirect URL and configure the access needed by the workflow.
3. Copy the client ID and client secret from that app.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Envoy (OAuth2)**.
2. Complete the connector configuration below. If you do not have access to these settings, ask your StackAI administrator to configure the connector.
3. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
4. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connector configuration**

| StackAI field | Required  | What to enter                                                                                                                                                                                      |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth Scopes  | Read-only | Permissions required for the Envoy visitor, employee, and desk actions. This value is shown for reference; it is not an editable credential.                                                       |
| Client ID     | Yes       | Client ID of an unlisted Envoy app configured to install 'Externally using OAuth2', with StackAI's callback as a redirect URL. [Provider instructions](https://dashboard.envoy.com/dev-dashboard). |
| Client Secret | Yes       | Client secret of the same Envoy app from the Dev Dashboard.                                                                                                                                        |
| Redirect URI  | Read-only | Use this redirect URI when configuring your OAuth application. This value is shown for reference; it is not an editable credential.                                                                |

#### Envoy (API Key)

Connect to Envoy with a Client API Key to register visitors, look up locations and employees, and reserve desks.

**Set up in Envoy**

1. Prepare the Envoy account or service that the workflow will access. Grant access to the required resources and operations.
2. **Client API Key:** Long-lived Client API Key from the Envoy Dev Dashboard (Configure your app > Envoy API Credentials). The app must be granted the scopes for the resources you use (locations, invites, employees, spaces, reservations).

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Envoy (API Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field  | Required | What to enter                                                                                                                                                                                                                                                                                |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client API Key | Yes      | Long-lived Client API Key from the Envoy Dev Dashboard (Configure your app > Envoy API Credentials). The app must be granted the scopes for the resources you use (locations, invites, employees, spaces, reservations). [Provider instructions](https://dashboard.envoy.com/dev-dashboard). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Envoy** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### List Locations

List Envoy locations.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `locations.read`

**Inputs**

| Field   | Type    | Required | Description                                            |
| ------- | ------- | -------- | ------------------------------------------------------ |
| Enabled | boolean | No       | Filter to active (true) or inactive (false) locations. |
| Limit   | integer | No       | Maximum number of locations to return. Default: 25.    |
| Page    | integer | No       | 1-based page number. Default: 1.                       |

**Outputs**

| Field     | Type        | Description                   |
| --------- | ----------- | ----------------------------- |
| Locations | dict\_array | Envoy locations on this page. |
| Count     | integer     | Number of locations returned. |

#### Create Invite

Register a visitor by creating an Envoy invite.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `invites.write`, `employees.read`, `locations.read`, `flows.read`
* `invites.write`, `employees.read` — Some dropdowns will not load options; enter IDs or emails directly.

**Inputs**

| Field                    | Type            | Required | Description                                                                            |
| ------------------------ | --------------- | -------- | -------------------------------------------------------------------------------------- |
| Location                 | select (string) | Yes      | Envoy location the visitor will arrive at. Options load from the selected connection.  |
| Visitor Full Name        | string          | Yes      | Full name of the visitor.                                                              |
| Visitor Email            | string          | No       | Email of the visitor (needed to send the invite email).                                |
| Expected Arrival (UTC)   | datetime        | Yes      | Expected arrival time in ISO-8601 UTC.                                                 |
| Expected Departure (UTC) | datetime        | No       | Expected departure time in ISO-8601 UTC.                                               |
| Host Employee            | select (string) | No       | Employee hosting the visitor. Options load from the selected connection.               |
| Sign-in Flow             | select (string) | No       | Sign-in flow (visitor type) for the invite. Options load from the selected connection. |
| Internal Notes           | textarea        | No       | Private notes attached to the invite.                                                  |
| Send Invite Email        | boolean         | No       | Email the invite to the visitor. Default: true.                                        |
| Sign-in Field Answers    | object          | No       | Pre-filled sign-in field answers keyed by field name.                                  |

**Outputs**

| Field     | Type   | Description               |
| --------- | ------ | ------------------------- |
| Invite    | object | The created invite.       |
| Invite ID | string | ID of the created invite. |

#### List Invites

List Envoy invites.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `invites.read`, `locations.read`, `employees.read`
* `invites.read` — Some dropdowns will not load options; enter IDs or emails directly.

**Inputs**

| Field                         | Type                      | Required | Description                                                                              |
| ----------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| Locations                     | multiple\_select (string) | No       | Limit to invites at these locations. Options load from the selected connection.          |
| Expected Arrival After (UTC)  | datetime                  | No       | Only invites expected after this time.                                                   |
| Expected Arrival Before (UTC) | datetime                  | No       | Only invites expected before this time.                                                  |
| Host                          | select (string)           | No       | Only invites hosted by this employee. Options load from the selected connection.         |
| Invitee Email                 | string                    | No       | Only invites for this visitor email.                                                     |
| Invite Type                   | select (string)           | No       | Visitor or employee invites. Available values: Visitor, Employee.                        |
| Approval Status               | select (string)           | No       | Filter by approval status. Available values: Pending, Approved, Denied, Awaiting Review. |
| Limit                         | integer                   | No       | Maximum number of invites to return. Default: 25.                                        |
| Page                          | integer                   | No       | 1-based page number. Default: 1.                                                         |

**Outputs**

| Field   | Type        | Description                 |
| ------- | ----------- | --------------------------- |
| Invites | dict\_array | Invites on this page.       |
| Count   | integer     | Number of invites returned. |

#### Get Invite

Get an Envoy invite by ID.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `invites.read`

**Inputs**

| Field  | Type            | Required | Description                                                                                                 |
| ------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| Invite | select (string) | Yes      | Invite to fetch (recent invites are listed; any ID is accepted). Options load from the selected connection. |

**Outputs**

| Field  | Type   | Description |
| ------ | ------ | ----------- |
| Invite | object | The invite. |

#### List Desks

List desks at Envoy locations.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `spaces.read`, `locations.read`
* `spaces.read` — Some dropdowns will not load options; enter IDs or emails directly.

**Inputs**

| Field         | Type                      | Required | Description                                                                                                              |
| ------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Locations     | multiple\_select (string) | No       | Limit to desks at these locations. Options load from the selected connection.                                            |
| Floors        | multiple\_select (string) | No       | Limit to desks on these floors (options load after picking locations). Options load from the selected connection.        |
| Neighborhoods | multiple\_select (string) | No       | Limit to desks in these neighborhoods (options load after picking locations). Options load from the selected connection. |
| Desk Name     | string                    | No       | Case-insensitive desk name search.                                                                                       |
| Limit         | integer                   | No       | Maximum number of desks to return. Default: 25.                                                                          |
| Page          | integer                   | No       | 1-based page number. Default: 1.                                                                                         |

**Outputs**

| Field | Type        | Description               |
| ----- | ----------- | ------------------------- |
| Desks | dict\_array | Desks on this page.       |
| Count | integer     | Number of desks returned. |

#### Create Desk Reservation

Reserve a desk for an employee.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `reservations.write`, `employees.read`, `locations.read`, `spaces.read`
* `reservations.write`, `employees.read` — Some dropdowns will not load options; enter IDs or emails directly.

**Inputs**

| Field            | Type            | Required | Description                                                                                       |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| Location         | select (string) | Yes      | Location where the desk is reserved. Options load from the selected connection.                   |
| Employee         | select (string) | Yes      | Employee the desk is reserved for. Options load from the selected connection.                     |
| Start Time (UTC) | datetime        | Yes      | Reservation start in ISO-8601 UTC.                                                                |
| End Time (UTC)   | datetime        | No       | Reservation end in ISO-8601 UTC.                                                                  |
| Desk             | select (string) | No       | Specific desk to reserve (leave empty to auto-assign). Options load from the selected connection. |

**Outputs**

| Field          | Type   | Description                    |
| -------------- | ------ | ------------------------------ |
| Reservation    | object | The created reservation.       |
| Reservation ID | string | ID of the created reservation. |
| Desk Name      | string | Name of the assigned desk.     |

#### List Employees

List or search Envoy employees.

**Permission alternatives**

The connection must grant one of these sets of permissions:

* `employees.read`

**Inputs**

| Field | Type    | Required | Description                                         |
| ----- | ------- | -------- | --------------------------------------------------- |
| Name  | string  | No       | Partial or full name to search.                     |
| Email | string  | No       | Partial or full email to search.                    |
| Limit | integer | No       | Maximum number of employees to return. Default: 25. |
| Page  | integer | No       | 1-based page number. Default: 1.                    |

**Outputs**

| Field     | Type        | Description                   |
| --------- | ----------- | ----------------------------- |
| Employees | dict\_array | Employees on this page.       |
| Count     | integer     | Number of employees returned. |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/envoy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
