> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/integrations/google-chat-app.md).

# Google Chat App

Google Chat Approval Workflow Integration with the Keeper Vault and Endpoint Privilege Manager

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fynckf07GxSpPTFP6PBHa%2FKeeper%20-%20GoogleChat%20Integration.jpg?alt=media&amp;token=9e8129ce-53d4-47a6-9c9f-39a4c577c1b7" alt=""><figcaption></figcaption></figure>

## Overview

The Keeper Google Chat App enables just-in-time access management and secure credential sharing within your Google Workspace environment. By integrating directly with Google Chat, teams can request, approve, and manage Keeper vault access without leaving their collaboration platform.

This self-hosted solution runs entirely on your infrastructure alongside Commander Service Mode, preserving Keeper's zero-knowledge security model. All communications between Google Chat and your Keeper vault remain end-to-end encrypted.

This guide covers deploying the Google Chat App using Cloud Pub/Sub for real-time message delivery. A Keeper Secrets Manager or KeeperPAM license is required — contact your account manager if you need to enable these features.

## Features

<table><thead><tr><th width="309.94140625">Feature</th><th>Description</th></tr></thead><tbody><tr><td><strong>Record Access Requests</strong></td><td>Users can request time-limited or permanent access to individual vault records, including KeeperPAM resources. Approvers see full request details and can grant custom permission levels. PAM User records support optional automatic credential rotation when temporary access expires.</td></tr><tr><td><strong>Folder Access Requests</strong></td><td>Grant users access to Classic Shared Folders or Nested Share Folders (NSF) with granular permission controls. Supports time-bound access with optional password rotation for PAM User folders upon expiration.</td></tr><tr><td><strong>External/One-Time Share Requests</strong></td><td>Generate secure, self-destructing share links for passwords, credentials, or sensitive data. Links can be view-only or editable for bi-directional sharing scenarios.</td></tr><tr><td><strong>Self-Serve Record Creation</strong></td><td>Empower engineers to add new credentials directly into shared folders they already have access to. The <code>/keeper-create-secret</code> command guides users through folder selection and record creation, with automatic admin notifications.</td></tr><tr><td><strong>Endpoint Privilege Manager Approvals</strong></td><td>Process KEPM elevation requests in real-time. When users need temporary admin privileges on their endpoints, approval cards appear instantly in your designated Google Chat space.</td></tr><tr><td><strong>SSO Cloud Device Approvals</strong></td><td>Authorize new SSO Cloud devices through Google Chat when Keeper Automator is not deployed. Admins receive device approval requests and can approve or deny with a single click.</td></tr></tbody></table>

***

## Prerequisites

#### Infrastructure Requirements

The Keeper Google Chat App follows a self-hosted architecture where your organization maintains full control over the integration components. This design ensures that sensitive credential data never passes through external services.

<table><thead><tr><th width="262.71484375">Requirement</th><th>Details</th></tr></thead><tbody><tr><td>Linux VM</td><td>Any VM in the cloud or on-prem that can establish outbound HTTPS connections to Google Chat and Keeper services.</td></tr><tr><td>Docker</td><td>Docker is the recommended method for setting up the service</td></tr><tr><td>Keeper Commander</td><td>Service Mode running and accessible</td></tr><tr><td>Keeper Secrets Manager</td><td>Either Keeper Secrets Manager or KeeperPAM license used for retrieving the secret configuration data</td></tr><tr><td>Google Workspace Account</td><td>Administrator access for Chat app registration and API enablement</td></tr><tr><td>Google Cloud Project</td><td>Houses the Pub/Sub infrastructure and service credentials</td></tr></tbody></table>

{% hint style="warning" %}
Important: The `gchat-app-setup` command requires Keeper Secrets Manager (KSM) to be activated. If KSM is not available, please contact your account manager.
{% endhint %}

## Setup Steps

Configuring the Google Chat App involves setting up Google Cloud resources, registering the Chat application, and deploying the containerized services:

Follow these steps to configure the Google Chat App:

1. [Set Up Google Cloud Project](#step-1.-set-up-google-cloud-project)
2. [Create a service account and key](#step-3.-generate-service-credentials)
3. [Configure Pub/Sub Messaging](#step-3.-configure-pub-sub-messaging)
4. [Grant IAM permissions](#step-4.-grant-iam-permissions)
5. [Register the Chat Application](#step-5.-register-the-chat-application)
6. [Prepare the Approvals Space](#step-6.-prepare-the-approvals-space)
7. [Commander Service Mode Setup](#step-7.-commander-service-mode-setup)
8. [Run Google Chat App Setup Command](#step-8.-run-google-chat-app-setup-command)
9. [Deploy to Docker Environment](#step-9.-deploy-to-docker-environment)

***

### Step 1. Set Up Google Cloud Project

1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a dedicated project for the Keeper (Name as - Keeper Security Google chat App ).

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F0EnwfYJWtERJ7G2gdAaK%2Fsetup%20screen%201.png?alt=media&amp;token=71edf8fb-8c5c-4a95-b508-c3fa192a63c4" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Record your Project ID — this identifier is required throughout the setup proces&#x73;**.**
{% endhint %}

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fz8m9Yt84Nb0aHBQNiQ0k%2Fproject%20id.png?alt=media&amp;token=1dfba916-7ca9-4621-960f-535a03128930" alt=""><figcaption></figcaption></figure>

3. Enable the necessary APIs:

* Open APIs & Services → Library
* Locate/search and enable the Google Chat API

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FfZgSsBdlTgrel210uqck%2Fsetup%20screen%202.png?alt=media&amp;token=825989f6-26ec-4862-9ce5-e7d3ec5e5163" alt=""><figcaption></figcaption></figure>

* Locate/search and enable the Cloud Pub/Sub API

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fk5vgsD7YYkZlDBZXGG4o%2Fsetup%20screen%203.png?alt=media&amp;token=d65668ea-120f-4a25-993a-22861e5773c8" alt=""><figcaption></figcaption></figure>

***

#### Step 2. Create a service account and key <a href="#step-3.-generate-service-credentials" id="step-3.-generate-service-credentials"></a>

This account lets the app pull events from Pub/Sub and post messages to Chat.

1. Go to IAM & Admin → Service Accounts
2. Select Create Service Account

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FgQ6lWDUEMiAVbApztsgE%2Fsetup%20screen%204.png?alt=media&amp;token=8d409c07-12e1-43d4-88a4-25db1806e366" alt=""><figcaption></figcaption></figure>

3. Enter a descriptive name: `keeper-chat-worker`  -> create
4. Open the account -> **Keys -> Add key -> Create new key -> JSON**.
5. Rename and Save the downloaded file as `service-account.json` .

{% hint style="info" %}
The  `service-account.json`  will be used in **Step 8.**
{% endhint %}

***

### Step 3. Configure Pub/Sub Messaging

Cloud Pub/Sub serves as the message broker between Google Chat and your self-hosted application. This pull-based approach eliminates the need for public endpoints or inbound firewall rules.

a. Create the Topic:

1. In the Cloud Console, open **Pub/Sub -> Topics**
2. Enter Topic ID: `keeper-chat-events`
3. Disable "Add a default subscription" (we'll create a custom one)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FPJdJDU3OeEwOjBNumxDr%2Fscreen%206.png?alt=media&amp;token=d6a29776-5f7c-44bf-a625-0619628493a6" alt=""><figcaption></figcaption></figure>

Leave everything else at defaults and click **Create ->** Confirm with Create

b. Create the Subscription:

1. Navigate to Pub/Sub -> Subscriptions ([direct link](https://console.cloud.google.com/cloudpubsub/subscription/list))
2. Select Create Subscription

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FfCIqyHQ2dvXcu1SB1yS9%2Fscreen%206.png?alt=media&amp;token=1e74dcc1-22cd-42c5-94a7-11d79d7e8ad3" alt=""><figcaption></figcaption></figure>

3. Enter Subscription ID: `keeper-chat-events-sub`
4. Choose the topic created above from Step 3(a).
5. Configure delivery settings:
   * Delivery type: Pull
   * Acknowledgement deadline: `60 seconds`
6. Leave all other fields at defaults and click **Create**.

***

### Step 4. Grant IAM permissions

Two separate grants are required. Missing either causes **"Keeper Security is not responding"** or events never arriving.

#### a. Let Google Chat publish to the topic

1. **Pub/Sub -> Topics -> `keeper-chat-events` -> Permissions -> Add Principle.**

Add the following as **Pub/Sub Publisher**:

| Principal                                  | Role              |
| ------------------------------------------ | ----------------- |
| `chat-api-push@system.gserviceaccount.com` | Pub/Sub Publisher |

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FPB1jHzd5OqHy5SdCZGLA%2Fscreen%208.png?alt=media&amp;token=d70d2ad0-8e49-45f3-ac4d-99773cb5317b" alt=""><figcaption></figcaption></figure>

#### b. Let the worker read the subscription

**Pub/Sub -> Subscriptions -> `keeper-chat-events-sub` -> Permissions -> Add Principle.**

| Principal                                                      | Role               |
| -------------------------------------------------------------- | ------------------ |
| `keeper-chat-worker@<YOUR_PROJECT_ID>.iam.gserviceaccount.com` | Pub/Sub Subscriber |

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FFNbayR6MH6oPEJnGlsjJ%2Fscreen%209.png?alt=media&amp;token=5be7a7c5-f549-44ca-b302-34f2823b330b" alt=""><figcaption></figcaption></figure>

***

### Step 5. Register the Chat Application

{% hint style="warning" %}
Important: Leave "Deploy as a Google Workspace Add-on" unchecked. Enabling this option locks your configuration and prevents future modifications.
{% endhint %}

1. Return to [Google Cloud Console](https://console.cloud.google.com/)
2. Open APIs & Services -> Enabled APIs & services
3. Click on Google Chat API

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F78dUFPjW1bTKRtKkWGVc%2Fscreen%2010.png?alt=media&amp;token=25476e23-5653-4a49-96b8-94f4157f5bd7" alt=""><figcaption></figcaption></figure>

4. Select the Configuration tab
5. Complete the application profile:

{% hint style="info" %}
**Build this Chat app as a Google Workspace add-on:** leave **UNCHECKED**.
{% endhint %}

| Setting                             | Value                                                                                                                                          |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| App name                            | `Keeper Security`                                                                                                                              |
| Avatar URL                          | [`https://keeper-email-images.s3.amazonaws.com/common/256x256_icon.png`](https://keeper-email-images.s3.amazonaws.com/common/256x256_icon.png) |
| Description                         | `Keeper vault credentials access in chat`                                                                                                      |
| Interactive features                | Enabled                                                                                                                                        |
| Join spaces and group conversations | Enabled                                                                                                                                        |
| Connection settings                 | Cloud Pub/Sub                                                                                                                                  |
| Pub/Sub topic name                  | `projects/YOUR_PROJECT_ID/topics/keeper-chat-events`                                                                                           |

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FUXlGLuhEaP7lvtj467Hx%2Fscreen%2011.png?alt=media&amp;token=44b48b27-6f6f-4741-a3cf-3301ea3b2dd1" alt=""><figcaption></figcaption></figure>

6. Register the slash commands:

<table><thead><tr><th width="226.640625">Command</th><th width="132.16015625">Command ID</th><th width="212.26171875">Description</th></tr></thead><tbody><tr><td><code>/keeper-request-record</code></td><td>1</td><td>Request access to a keeper vault record</td></tr><tr><td><code>/keeper-request-folder</code></td><td>2</td><td>Request access to a keeper shared folder</td></tr><tr><td><code>/keeper-external-share</code></td><td>3</td><td>Request access to a keeper vault record for External share</td></tr><tr><td><code>/keeper-create-secret</code></td><td>4</td><td>Create a new record to a shared folder in Keeper</td></tr></tbody></table>

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fb6wUYKoGCbIzb4DgXyGP%2Fscreen%2012.png?alt=media&amp;token=19c27918-b2f6-4d7c-94e1-8f75defc88d6" alt=""><figcaption></figcaption></figure>

7. Configure visibility under the Visibility section:
   * Add your **email address** under **Development/Testing Users**.&#x20;

{% hint style="info" %}
**Note:** Only the email addresses added here will be able to see and interact with the app during development and testing. Complete the remaining setup and verify that the Keeper Google Chat app is working as expected. Once verified, publish the app internally so that users across the organization can access and use it.
{% endhint %}

7. Save your configuration

***

### Step 6. Prepare the Approvals Space

Access requests and administrative notifications are posted to a designated Google Chat space where approvers can review and act on them.

1. Open [Google Chat](https://chat.google.com/)
2. Under Spaces, select Create space
3. Configure the space:
   * Name: `Keeper-vault-Approvers` (or your preference)
   * Add team members who should handle access requests

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FK7rlW3gaCp0ldyoWaxr0%2Fscreen%2013.png?alt=media&amp;token=e3e085c6-56d6-458e-8d46-02f8f5e036b9" alt=""><figcaption></figcaption></figure>

4. Install the Keeper app in this space:

* Click the space name → View details
* Select Apps & integrations → Add apps
* Find "Keeper Security" and add it

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FyVWNIzKYzU7aqUZK5YW4%2Fscreen%2014.png?alt=media&amp;token=9e934f82-91c0-4f90-bdca-8a7144ee6ec3" alt=""><figcaption></figcaption></figure>

5. Obtain the Space ID:

* The URL shows: `https://chat.google.com/chat/XXXXXXXXX`
* Your Space ID is: `spaces/XXXXXXXXX`

{% hint style="info" %}
`Space ID`  will be used in step 8.
{% endhint %}

***

### Step 7. Commander Service Mode Setup

To enable the service to authenticate and execute commands within the Keeper tenant, an authorized **Keeper Commander configuration file** must be created. This configuration can be generated on a host computer or workstation.

* [Install Keeper Commander](/keeperpam/commander-cli/commander-installation-setup.md) locally on your machine
* If required, create a new Keeper service account dedicated to this integration, ensuring it has access to the relevant records and folders and the ability to perform record and folder sharing.
* Login to Commander with the Keeper Service account `(serviceuser@company.com)`

```
keeper shell
My Vault> login serviceuser@company.com
```

* Complete the authentication process including any 2FA requirements. Once you are fully authenticated, proceed to Step 4.

***

### Step 8. Run Google Chat App Setup Command

The `gchat-app-setup` command generates a `docker-compose.yml` used to run the Google Chat App and Commander Service Mode.

From the Commander shell:

```
gchat-app-setup
```

**Command Line Options**

| Parameter                       | Description                                    | Default Value                                 |
| ------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| --folder-name (optional)        | Name for the shared folder                     | Commander Service Mode - Google Chat App      |
| --app-name (optional)           | Name for the Secrets Manager app               | Commander Service Mode - KSM App              |
| --config-record-name (optional) | Name for the Commander config record           | Commander Service Mode Docker Config          |
| --gchat-record-name (optional)  | Name for the Google Chat config record         | Commander Service Mode Google Chat App Config |
| --config-path (optional)        | Path to config.json file                       | \~/.keeper/config.json                        |
| --timeout (optional)            | Device timeout setting                         | 30d                                           |
| --skip-device-setup (optional)  | Skip device registration if already configured | false                                         |

Example with custom names:

```
gchat-app-setup --folder-name "My Google Chat Integration" --timeout 7d
```

#### **Phase 1: Docker Service Mode Setup**

The command configures KSM and uploads the configuration file for Docker Service Mode.

```bash
Phase 1: Running Docker Service Mode Setup
═══════════════════════════════════════════════════════════
    Docker Setup
═══════════════════════════════════════════════════════════

[1/7] Checking device settings...
[2/7] Creating shared folder 'Commander Service Mode - Google Chat App'...
[3/7] Creating record 'Commander Service Mode Docker Config'...
[4/7] Uploading config.json attachment...
[5/7] Creating Secrets Manager app 'Commander Service Mode - KSM App'...
[6/7] Sharing folder with app...
[7/7] Creating client device and generating config...

✓ Docker Setup Complete!
```

**Service Configuration**

Configure the Commander Service port:

<table><thead><tr><th width="155.578125">Prompt</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Port</td><td>Port number for Commander Service Mode (1024-65535).</td><td>8900</td></tr></tbody></table>

**Tunneling Configuration (Optional)**

<table><thead><tr><th width="236.83984375">Prompt</th><th>Description</th></tr></thead><tbody><tr><td>Ngrok Auth Token</td><td>Your ngrok authentication token for public URL generation.</td></tr><tr><td>Ngrok Custom Domain</td><td>Custom ngrok domain (for example, myapp.ngrok.io).</td></tr><tr><td>Cloudflare Tunnel Token</td><td>Cloudflare tunnel token for public URL generation.</td></tr><tr><td>Cloudflare Custom Domain</td><td>Your Cloudflare domain (for example, gchat.company.com).</td></tr></tbody></table>

{% hint style="warning" %}
Ngrok and Cloudflare are mutually exclusive. This is NOT required for the Google Chat App. You may need a tunnel if you also use other integrations such as the Jira app. Cloudflare example domain: `gchat.company.com`.
{% endhint %}

#### **Phase 2: Google Chat App Integration Setup**

Enter the values from the earlier GCP and Google Chat setup steps:

<table><thead><tr><th width="148.7578125">Prompt</th><th width="214">Description</th><th>Example</th></tr></thead><tbody><tr><td>Path to service account JSON file (required)</td><td>Path to the GCP service account JSON key used for Pub/Sub pull and Google Chat API. Inline JSON paste is not accepted.</td><td>/path/to/service-account.json</td></tr><tr><td>Project ID (required)</td><td>GCP project ID. Press Enter to use <code>project_id</code> from the service account JSON. If it differs from the SA project, confirm before continuing.</td><td>your-gcp-project-id</td></tr><tr><td>Topic ID (required)</td><td>Pub/Sub topic that receives Google Chat events. </td><td>keeper-chat-events</td></tr><tr><td>Subscription ID (required)</td><td>Pub/Sub subscription used to pull events. </td><td>keeper-chat-events-sub</td></tr><tr><td>Space ID (required)</td><td>Google Chat space where approval cards are posted. Must start with <code>spaces/</code> and include a space id.</td><td>spaces/&#x3C;YOUR_ID></td></tr><tr><td>/keeper-request-record command ID</td><td>Slash command ID  should be same as registered in slash command id in console.</td><td>1</td></tr><tr><td>/keeper-request-folder command ID</td><td>Slash command ID  should be same as registered in slash command id in console.</td><td>2</td></tr><tr><td>/keeper-external-share command ID</td><td>Slash command ID  should be same as registered in slash command id in console.</td><td>3</td></tr><tr><td>/keeper-create-secret command ID</td><td>Slash command ID  should be same as registered in slash command id in console.</td><td>4</td></tr><tr><td>Enable PEDM? (optional)</td><td>Enable Endpoint Privilege Manager approvals (y/n).</td><td>y</td></tr><tr><td>PEDM Polling Interval (optional)</td><td>Seconds. Default 120.</td><td>120</td></tr><tr><td>Enable Device Approvals? (optional)</td><td>Enable SSO Cloud device approvals (y/n).</td><td>y</td></tr><tr><td>Device Approval Polling Interval (optional)</td><td>Seconds. Default 120.</td><td>120</td></tr></tbody></table>

After setup, the command creates a Google Chat configuration record. It includes these fields:

* `google_service_account_json` (secret), `google_project_id`, `google_topic_id`, and `google_subscription_id`
* `chat_approvals_space_id`, `chat_command_request_record_id`, `chat_command_request_folder_id`, `chat_command_external_share_id`, and `chat_command_create_secret_id`
* Optional `pedm_*` and `device_approval_*` fields

The command generates a `docker-compose.yml` for Commander Service Mode and the Google Chat App.

{% code overflow="wrap" %}

```yaml
services:
  commander:
    container_name: keeper-service
    ports:
    - 127.0.0.1:<port>:<port>
    image: keeper/commander:latest
    command: service-create -p <port> -c 'search,share-record,share-folder,record-add,one-time-share,pedm,device-approve,get,ls,share-report,tree' -f json -q y -ur <CONFIG_RECORD_UID> --ksm-config <KSM_CONFIG_BASE64_VALUE> --record <CONFIG_RECORD_UID>
    healthcheck:
      test:
      - CMD-SHELL
      - python -c "import sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://localhost:<port>/health', timeout=2).status == 200 else 1)"
      interval: 60s
      timeout: 3s
      start_period: 10s
      retries: 30
    restart: unless-stopped
  gchat-app:
    container_name: keeper-gchat-app
    image: keeper/gchat-app:latest
    environment:
      KSM_CONFIG: <KSM_CONFIG_BASE64_VALUE>
      COMMANDER_RECORD: <CONFIG_RECORD_UID>
      GCHAT_RECORD: <GCHAT_CONFIG_RECORD_UID>
    depends_on:
      commander:
        condition: service_healthy
    restart: unless-stopped
```

{% endcode %}

Once setup is complete, terminate the Commander session. Delete the local `.keeper/config.json` file to prevent device token conflicts.

```
My Vault> quit
$ rm ~/.keeper/config.json
```

***

### Step 9. Deploy to Docker Environment

Set up Docker Compose on the Linux VM or host that runs Commander Service Mode.

* Launch a Linux VM or prepare a Linux host and connect through SSH.
* Install `docker` and `docker-compose`. See the [Installing Docker on Linux](/keeperpam/privileged-access-manager/references/installing-docker-on-linux.md).
* Transfer the generated `docker-compose.yml` file from Step 7 to the host.

Start the services:

```
docker compose up -d
```

**Service Startup Sequence**

1. Commander Service starts and stores its API key and URL in the vault record.
2. Health checks validate the Commander Service.
3. Google Chat App starts after the health check passes.

**Verify Successful Startup**

Check the container status:

```bash
$ docker ps
NAME              STATUS                    PORTS
keeper-service    Up (healthy)              127.0.0.1:<port> -> <port>/tcp
keeper-gchat-app  Up
```

View Commander Service logs:

```bash
$ docker logs keeper-service
[2026-01-21 10:00:00] Starting Commander Service Mode...
Generated API key: ****nQ= (stored in vault record: <CONFIG_VAULT_RECORD>)
Commander Service starting on <SERVICE_URL>/api/v2
Keeper Commander Service initialization complete
```

View Google Chat App logs:

```
docker logs keeper-gchat-app
```

**After verifying that the app is working as expected, follow the instructions in the link below to publish the app internally. Once published, users within the organization will be able to install the Keeper Google Chat app and use it to raise access requests.**

[Publishing the Keeper Google Chat App Internally](/keeperpam/secrets-manager/integrations/google-chat-app/publishing-the-keeper-google-chat-app-internally.md)

***

### Command Reference for Requesting User

#### /keeper-request-record

Request access to a specific Keeper record.

Syntax:

```
/keeper-request-record <record-uid-or-description> <justification>

Example:-
/keeper-request-record kR3cF9Xm2Lp8NqT1uV6w Emergency server access
/keeper-request-record "prod db EU region" Need to run migration
```

#### /keeper-request-folder

Request access to a shared folder.

Syntax:

```
/keeper-request-folder <folder-uid-or-description> <justification>

Example:-
/keeper-request-folder kF8zQ2Nm5Wx9PtR3sY7a Need staging access
/keeper-request-folder "Staging Team Folder" Need staging access
```

#### /keeper-create-secret

Create a new secret record in a shared folder that has been shared with you.

Syntax:

<pre><code>/keeper-create-secret

This command opens an interactive form with the following steps:

1.Select a Shared Folder — Only shared folders that have been shared with your Keeper account are displayed.
<strong>2.Select a Subfolder (optional) — If the selected shared folder contains subfolders, you can choose one.
</strong>3.Enter Record Details — Fill in the record fields:
   a. Title (required)
   b. Login (optional)
<strong>   c. Password (optional — Enter password (or check auto-generate checkbox above))
</strong>   d. URL (optional)
   e. Notes (optional)
Confirmation — The modal displays the created Record UID and folder path.
Admins are notified in the approvals space: "User @name created record &#x3C;UID> in SharedFolder / Subfolder"

Note: The requesting user's Google Workspace email must match their Keeper account email for folder visibility to work correctly.
</code></pre>

#### /keeper-external-share

Request a one-time share link for a record for external user or vendor.

Syntax:

```
/keeper-external-share <record-uid-or-description> <justification>

Example:-
/keeper-external-share kR3cF9Xm2Lp8NqT1uV6w Need to share with contractor John
/keeper-external-share "AWS Production Password" Sharing with vendor
```

***

## Screenshots

The below screenshots demonstrate the core features of the Keeper Google chat App.

#### Interacting with the Google chat App for Requests

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FuM0WNC310oNQnofpDMh7%2Fcommand%20list%20screen.png?alt=media&amp;token=0268bca4-c5f6-406c-a131-640fe110664e" alt=""><figcaption></figcaption></figure>

***

#### Requesting Access to a Record (no UID provided)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FmLKpvqVa2oxdRNKqtk9r%2Facceess%20request%20to%20record(No%20UID%20provided).png?alt=media&amp;token=497720b6-1a38-444e-9fc9-2a43f2ad4a8c" alt=""><figcaption></figcaption></figure>

***

#### Requesting Access to a Record (with UID provided)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FXdqm7PrqQ4a2nnBCy7yr%2Faccess%20request%20submitted.png?alt=media&amp;token=be67ac36-3ba1-4b4b-a270-03b5b2b4366d" alt=""><figcaption></figcaption></figure>

***

#### **Search for Nested/New Record Type \[NSF] - Admin View**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FZAb7ophVZn160rscOkcz%2FNSF%20view.png?alt=media&amp;token=5802d58b-142b-4200-bad5-93f3fe5a2b67" alt=""><figcaption></figcaption></figure>

***

#### Record Access Request - Admin View

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FwJntERgLovY9O8U0iEZf%2Frecord%20access%20request%20-%20admin%20view.png?alt=media&amp;token=1c7a7dcd-13af-424f-96f9-34da42d21bc7" alt=""><figcaption></figcaption></figure>

***

#### Requesting Access to a Folder (with UID provided)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FYfDux0yfBIwVQe0yK0FA%2FRequesting%20Access%20to%20a%20Folder%20(with%20UID%20provided).png?alt=media&amp;token=823db766-782b-483b-a378-89b96cd4cb7d" alt=""><figcaption></figcaption></figure>

***

#### Folder Access Request - Admin View

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FN40aVauf0EhysIVtP2D1%2FFolder%20Access%20Request%20-%20Admin%20View.png?alt=media&amp;token=e90dac5c-2ae1-4294-b70d-20abec1db963" alt=""><figcaption></figcaption></figure>

***

#### **NSF Folders Search with Permissions** - **Admin View**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FtFVK98SOZg2Vavznqcaf%2FNSF%20Folders%20Search%20with%20Permissions%20-%20Admin%20View.png?alt=media&amp;token=997c8330-869c-4cb6-b037-ea0339546341" alt=""><figcaption></figcaption></figure>

***

#### External/One-time Share Request for vendors

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F2KZlBogKyT4q5P87dcUI%2Fexternal%20share.png?alt=media&amp;token=25ee30ec-5f8f-4300-ad16-0e7d02381543" alt=""><figcaption></figcaption></figure>

***

#### **Classic and New Record Creation - Admin View**

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Fw7lOFztVNiZMT2nifMIx%2Fcreate%20new%20record.png?alt=media&amp;token=89d2252b-b844-4e45-9bb2-9efbb81c4fc8" alt=""><figcaption></figcaption></figure>

***

#### Self-Serve Record Creation (Requesting user)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FwY32QPfoQDPoJJ0AwzI6%2Fself-server-record%20creation%201.png?alt=media&amp;token=374c2ff5-69a4-488b-ade8-f8e7b88c7ab5" alt=""><figcaption></figcaption></figure>

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FyafRzombqO516BKXjwWn%2Fself-server-record%20creation%202.png?alt=media&amp;token=0de15292-7d38-4fe4-929b-11e211788d24" alt=""><figcaption></figcaption></figure>

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F7CylHxvFkaZ0xhwovuXS%2Fself-server-record%20creation%203.png?alt=media&amp;token=a1ec9fed-2ef6-45ea-9951-0d25f7ae8b94" alt=""><figcaption></figcaption></figure>

***

#### One-Time Share - Admin View with Search for Existing Record

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2Ft4tNjNkd3QAnbY9B3rBw%2FOne-Time%20Share%20-%20Admin%20View%20with%20Search%20for%20Existing%20Record.png?alt=media&amp;token=10a231f1-4b37-403e-a093-e1d0d1f34264" alt=""><figcaption></figcaption></figure>

***

#### Endpoint Privilege Manager - Approval for Elevation

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FOLvRg9XXlsb5bviQcVIG%2Fepm%20approval%20request.png?alt=media&amp;token=812eab46-0eea-4b14-bb10-6a86ccf8f132" alt=""><figcaption></figcaption></figure>

***

#### SSO Cloud Device Approval - Admin View

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FhIxt5l8jPtqfiz44pXwU%2Fcloud%20sso%20device%20approval.png?alt=media&amp;token=885c38e6-5e59-4e65-88b4-82acc297fde7" alt=""><figcaption></figcaption></figure>

***

## Updates

#### Updating the Commander Service Mode and Google Chat App Container

To update Commander or the Google Chat App, stop the services, update the containers, and restart them.

```bash
docker compose down
docker compose pull
docker compose up -d
```

***

## Troubleshooting

#### Startup Errors

<table><thead><tr><th>Error</th><th width="230.42578125">Cause</th><th>Solution</th></tr></thead><tbody><tr><td>Commander Service Mode is prompting for master password</td><td>Multiple config.json files are attached to the vault record</td><td>Run <code>gchat-app-setup</code> with a new folder name to create a new JSON configuration file.</td></tr><tr><td>[WARN] Warning: Cannot reach Keeper Service Mode</td><td>Service Mode is not running or has the wrong URL</td><td>Verify the service URL in the vault record.</td></tr></tbody></table>

***

#### Service Mode Errors

| Error                              | Cause                                             | Solution                                                    |
| ---------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| Failed to submit command: HTTP 403 | API key invalid or missing                        | Verify api\_key in config vault record matches service mode |
| Failed to submit command: HTTP 404 | Wrong API endpoint version                        | Use V2 endpoint: /api/v2/ (not /api/v1/)                    |
| Failed to submit command: HTTP 405 | Using wrong HTTP method                           | Ensure Service Mode is running with queue enabled           |
| Command timed out or failed        | Service Mode overloaded or command not registered | Register command in Service Mode; increase timeout          |
| No request\_id received from API   | Service Mode not using queue/async mode           | Restart Service Mode with queue enabled (V2)                |

***

#### Access Grant Errors

| Error                                        | Cause                                              | Solution                                                                       |
| -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------ |
| Record Not Found                             | Invalid UID or record deleted                      | Verify the record UID exists in Keeper vault                                   |
| Folder Not Found                             | Invalid folder UID                                 | Verify the folder UID exists in Keeper vault                                   |
| Invalid UID Type (record vs folder)          | Used wrong command for item type                   | Use /keeper-request-folder for folders, /keeper-request-record for records     |
| This user already has time-limited access... | Conflict with existing share                       | Revoke existing access first, then grant new permission                        |
| Share permissions require permanent access   | Trying to use duration with Can Share/Edit & Share | Share permissions (Can Share, Edit & Share, Change Owner) are always permanent |
| User share...failed                          | Permission conflict on folder                      | User may have incompatible existing access; revoke and re-grant                |

***

#### Search & Modal Errors

| Error                                    | Cause                                   | Solution                                                                |
| ---------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| No records found matching...             | Search query too specific or no matches | Try broader search terms; check record exists in vault                  |
| Search command timed out                 | Service Mode slow or vault very large   | Increase max\_wait in \_poll\_for\_result() or use more specific search |
| Error processing search modal submission | Modal data corrupted or expired         | Close modal and try again; check logs for specific error                |
| Modal shows "Searching..." forever       | Poll result never returned              | Check Service Mode logs; verify search command is registered            |

***

#### External/One-Time Share Errors

| Error                                                   | Cause                                   | Solution                                                             |
| ------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- |
| one-time share links can not be created for PAM records | Commander doesn't support               | Request for non-pam records                                          |
| Share link created but URL not found in response        | Unexpected Service Mode response format | Check Service Mode version; verify one-time-share command registered |
| Failed to create one-time share                         | Record may not be shareable             | Verify user has share permissions on the record                      |

***

#### Record Creation Errors

| Error                                         | Cause                                    | Solution                                                   |
| --------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
| Failed to create record                       | Missing required fields or command error | Ensure title, login, and password are provided             |
| Record created but UID could not be retrieved | Search after creation failed             | Record exists but search timed out; manually search for it |

***

#### KEPM Errors

| Error                               | Cause                                | Solution                                                                                                       |
| ----------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| No data returned                    | KEPM feature not enabled             | Enable KEPM in your Keeper enterprise settings. Ensure that your service user has necessary admin permissions. |
| KEPM sync failed                    | Service Mode can't reach KEPM server | Check network connectivity and KEPM configuration                                                              |
| Failed to approve/deny KEPM request | Request may have expired             | Check if request is still pending; it may have auto-expired                                                    |

### References

* [Commander CLI Overview](/keeperpam/commander-cli/overview.md)
* [Commander Service Mode](/keeperpam/commander-cli/service-mode-rest-api.md)
* [Endpoint Privilege Manager](/keeperpam/endpoint-privilege-manager/overview.md)
* [SSO Connect Cloud](https://docs.keeper.io/sso-connect-cloud/)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/integrations/google-chat-app.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.