Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Freshservice Workflow

Secure fulfillment of Keeper vault access and approval requests in Freshservice

Overview

The Keeper Security Freshservice Workflow app enables IT and security teams to fulfill Keeper vault access and approval requests directly from the Freshservice ticket sidebar. Agents search the Keeper vault, configure share permissions, and approve or deny requests without leaving the ticket.

All Keeper-side operations are executed through a customer-hosted Keeper Commander ServiceMode endpoint over HTTPS. The app does not store Keeper credentials in Freshservice tickets.

This app is the fulfillment layer for governed Keeper access in Freshservice.

Marketplace Link

Features

  • Ticket sidebar fulfillment for vault access requests and Keeper approval tickets

  • Vault search — search records and folders before approving access

  • Share Record — grant view, edit, share, edit-share, or change-owner access (Classic and Nested records)

  • Share Folder — grant or revoke Classic or Nested folder access with manage-records / manage-users options

  • One-Time Share — generate a self-destructing share link and surface the URL to the agent

  • Approve EPM — approve or deny Endpoint Privilege Manager (KEPM) requests

  • Approve Device — approve or deny Cloud SSO device enrollment requests

  • Install-time health check — verifies ServiceMode reachability and API key validity on install

  • Optional Activity notes — posts public notes to the ticket Activity tab after approve or deny when a Freshservice API key is configured

  • Apps launcher fallback — full-page entry point when the ticket sidebar surface is unavailable on a tenant

Prerequisites

  • Freshservice account with permission to install marketplace or custom apps

  • Keeper Commander ServiceMode deployed on a publicly reachable HTTPS endpoint (reverse proxy, load balancer, cloud tunnel, etc.)

  • ServiceMode API key with permissions to perform share, approval, and vault-search operations on behalf of the configured Keeper service account

  • After install, a Freshservice admin must manually create and publish a service catalog item with three required custom fields:

    • Request Type (dropdown)

    • Requirements (paragraph)

    • Justification for this request (paragraph)

    See Step 3. The app does not create catalog items on install.

  • Request Type options: Record Access, Folder Access, One-Time Share Link

  • Optional — Keeper Security ITSM for Freshservice: required only for automated EPM and device approval ticket creation from Keeper alerts

  • Optional — Freshservice admin API key: enables Activity notes and server-side ticket enrichment; fulfillment still works without it

Roles Required in Freshservice

Task
Recommended access

Install and configure the app

Account Admin

Fulfill vault access requests

Agent with access to assigned tickets

Approve or deny EPM / device requests

Security or IT admin agent

Manage service catalog items

Admin or service catalog manager

View app installation and support

Admin

Configuration Instructions

Step 1 — Deploy Keeper Commander ServiceMode

  1. Install Keeper Commander on a server reachable from the public internet (Freshworks cloud must reach your ServiceMode host).

  2. Create and start ServiceMode with the commands required for this integration.

    Supported commands should include at minimum:

    sync-down, search, share-record, nsf-share-record, share-folder, nsf-share-folder, one-time-share, device-approve, epm

  3. Note the hostname (no https://, no path) and the generated API key.

Sample service-create session:

For Docker deployment, tunneling, and advanced settings, see:

Step 2 — Install the app in Freshservice

  1. Log in to Freshservice with Account Admin privileges.

  2. Navigate to Admin → Apps.

  3. Search for Keeper Security Workflow and click Install (or upload the custom app package).

  4. On the installation screen, enter the parameters below and click Install (or Save when editing).

Parameter
Required
Description

Keeper Commander ServiceMode Host

Yes

Hostname only — no https:// and no path. Example: keeper-sm.example.com

ServiceMode API Key

Yes

API key from ServiceMode setup. Stored encrypted; not displayed after save.

Freshservice API Key

No

Admin API key used server-side to load ticket details and post public Activity notes after approve or deny. Leave blank to skip Freshservice API calls. The app does not create service catalog items, change ticket status (for example, to Resolved), or resolve tickets automatically.

Freshservice Domain

When Freshservice API key set

Hostname only, e.g. yourcompany.freshservice.com (no https://). Used server-side for ticket enrichment and Activity notes.

  1. On install, the app runs a health check against ServiceMode. Install fails if the endpoint is unreachable or the API key is rejected.

Note: Password fields appear empty after save. Keys are stored securely and are not shown again in the install screen.

Step 3 — Service catalog setup (required, manual)

The app does not create service catalog items on install. Install only runs a ServiceMode health check. A Freshservice admin must create and publish the catalog item after the app is installed.

A. Create the service item

  1. Go to Admin → Service Catalog.

  2. Click New Service Item (or edit an existing item).

  3. On the General tab, set:

    • Name: Request Keeper Vault Access (recommended)

    • Short description: Request access to a Keeper vault record, folder, or one-time share link

    • Category: your choice (for example Security, Identity, or IT)

The sidebar recognizes Keeper vault access tickets when the subject or description includes phrases such as request keeper vault access or keeper vault access.

B. Add custom fields (all required)

  1. Open the Custom Fields section for this catalog item.

  2. Add these three required fields:

Added Custom fields
Request type dropdown field
Requirement paragraph field
Justification paragraph field
#
Field type
Label
Required
Options / guidance

1

Dropdown

Request Type

Yes

Record Access, Folder Access, One-Time Share Link (use these exact labels)

2

Paragraph

Requirements

Yes

Requester describes what they need (record, folder, or use case)

3

Paragraph

Justification for this request

Yes

Requester explains why access is needed

  1. Mark each field Required so requesters cannot submit without completing them. All four Behavior checkboxes should be checked.

Note: Freshservice assigns internal field names automatically (for example when the label is "Request Type"). You do not need to set API names manually. The Keeper app detects the request type from the dropdown value on the ticket.

C. Publish and verify

  1. Publish the item to the employee portal.

  2. Submit a test request for each Request Type option.

  3. Open each ticket and confirm the Keeper Vault sidebar tab appears and shows the correct flow (record, folder, or one-time share).

Request Type
Sidebar behavior

Record Access

Search records → set permissions → Approve runs shareRecord

Folder Access

Search folders → set permissions → Approve runs shareFolder

One-Time Share Link

Search records → set expiration and editable option → Approve runs createOneTimeShare

Step 4 — Configure Keeper alerts for EPM and device tickets (optional)

EPM and device approval fulfillment in this app depends on tickets created by the Keeper Security ITSM for Freshservice app.

  1. Install and configure Keeper Security ITSM for Freshservice on your tenant.

  2. In Keeper Admin Console → Reporting and Alerts → Alerts, create or edit an alert configuration.

  3. Add a Webhook recipient with the URL and token from the ITSM app guided setup.

  4. Enable alert types for:

    • Endpoint Privilege Manager approval requests

    • Cloud SSO device admin approval requests

  5. When alerts fire, the ITSM app creates Freshservice tickets with keeper_request_id (and related fields). This Workflow app reads those fields for approve/deny.

This Workflow app does not ingest webhooks directly.

Example Use Cases

Request access to a Keeper vault record

  1. Trigger: An employee submits a Freshservice service catalog request for Record Access.

  2. Approval: The request is approved per your Freshservice approval workflow.

  3. Fulfillment: An agent opens the ticket, opens the Keeper Vault sidebar tab, searches for the record, selects permissions, and clicks Approve.

  4. Result: Commander runs share-record and grants access to the requester. If configured, a public Activity note is added to the ticket.

Request access to a shared folder

  1. Trigger: An employee submits a Folder Access catalog request.

  2. Approval: The request is approved.

  3. Fulfillment: The agent searches folders in the sidebar, selects manage-records / manage-users options (or a Nested folder role), and approves.

  4. Result: Commander runs share-folder or nsf-share-folder. The requester receives folder access.

One-time share link

  1. Trigger: An employee submits a One-Time Share Link request.

  2. Fulfillment: The agent searches for the record, sets link expiration and whether the recipient can edit, and approves.

  3. Result: Commander returns a one-time share URL (https://…/vault/share#…). The agent forwards the link to the requester from the sidebar or Activity note.

Deny a vault access request

  1. Trigger: An approved vault access ticket requires denial (policy, wrong record, etc.).

  2. Action: The agent clicks Deny request in the sidebar and enters a justification.

  3. Result: No Keeper share command is executed. If a Freshservice API key is configured, a public Activity note records the denial and justification.

Endpoint Privilege Manager (EPM) approval

  1. Trigger: A user requests privilege elevation on an endpoint. Keeper Admin Console sends an alert; the Keeper Security ITSM for Freshservice app creates a ticket with keeper_request_id.

  2. Fulfillment: A security admin opens the ticket and clicks Approve or Deny in the Keeper sidebar.

  3. Result: Commander runs epm approval action --approve or --deny. The ticket is annotated in Activity when configured.

Freshservice ITSM app cerated ticket for EPM approval request

Cloud SSO device approval

  1. Trigger: A user enrolls a device pending admin approval. The ITSM app creates a Freshservice ticket.

  2. Fulfillment: An admin approves or denies from the Keeper sidebar using the email or device id on the ticket.

  3. Result: Commander runs device-approve.

Freshservice ITSM app created ticket for Device approval request

Agent Fulfillment Guide

Open the Keeper sidebar

  1. Open a Freshservice ticket for a Keeper vault access or approval request.

  2. Click the Keeper Vault tab in the ticket sidebar.

If the sidebar tab does not appear on your tenant, open the app from Apps in the Freshservice launcher (same UI, full-page entry point).

Fulfill a Record Access request

  1. Confirm the ticket request type is Record Access.

  2. In the sidebar, choose Records search scope.

  3. Enter at least 2 characters and click Search.

  4. Select a result from the list.

  5. Enter the Recipient email.

  6. Choose Classic record permission or Nested record role depending on record type.

  7. Optionally set Expiration when the permission model supports time-limited access.

  8. Click Approve.

Fulfill a Folder Access request

  1. Confirm the ticket request type is Folder Access.

  2. Choose Folders search scope.

  3. Search and select the target folder.

  4. Enter the Recipient email.

  5. For Classic folders, choose:

    • No User Permissions

    • Manage records

    • Manage users

    • Manage records & users

  6. For Nested share folders, choose the appropriate Nested folder role.

  7. Optionally set expiration.

  8. Click Approve.

Fulfill a One-Time Share Link request

  1. Confirm the ticket request type is One-Time Share Link.

  2. Search and select the record.

  3. Set Expiration (default in the UI: 5 minutes; options include 5m, 10m, 30m, 1h, 4h, 8h, 24h, 7d).

  4. Optionally check Can edit for a bidirectional share.

  5. Click Approve.

  6. Copy the one-time share URL from the sidebar and send it to the requester.

Deny a vault access request

  1. Click Deny request (available without searching the vault).

  2. Enter a justification (required, up to 500 characters).

  3. Click Confirm denial.

No Keeper share command is executed.

Approve or deny EPM / device requests

  1. Open a ticket created by the Keeper ITSM app for EPM or device approval.

  2. The sidebar shows Approve and Deny only (no vault search).

  3. Review the request id shown on the ticket.

  4. Click Approve or Deny.

For device approvals, request_id accepts either the user's email or the pending device id from the ticket.

Permission Models

The app supports Classic and Nested Keeper permission models.

Classic record permissions

Permission
Commander behavior

View

Read-only access

Edit

Read + modify (--write)

Share

Read + re-share (--share)

Edit & share

Read + modify + re-share (--write --share)

Change owner

Transfer ownership (--action owner, irreversible)

Nested record roles

Role
Description

Viewer

Read-only

Share Manager

Can manage sharing

Content Manager

Can manage record content

Content & Share Manager

Content + sharing

Full Manager

Full management

Transfer Ownership

Transfer record ownership

Classic folder permissions

Option
manage_records
manage_users

No User Permissions

off

off

Manage records

on

off

Manage users

off

on

Manage records & users

on

on

Expiration notes

  • Some permission levels do not support time-limited expiration (for example, Classic share, edit-share, change-owner).

  • When expiration is not supported for the selected permission, the expiration control is hidden and access is granted without expiry.

  • One-time share expiration uses Commander units: Nmi (minutes), Nh (hours), Nd (days). The UI normalizes friendly forms such as 30m to 30mi.

Commander Commands Reference

Before any vault share command (shareRecord, shareFolder, createOneTimeShare), the server runs sync-down to refresh the local vault cache. epm sync-down runs only before EPM approval actions.

Action
Commander command

Vault sync (before share / OTS)

sync-down

Share record (view)

share-record --email <email> --action grant <record_uid>

Share record (edit)

share-record --email <email> --action grant --write <record_uid>

Share record (share)

share-record --email <email> --action grant --share <record_uid>

Share record (edit-share)

share-record --email <email> --action grant --write --share <record_uid>

Share record (change-owner)

share-record --email <email> --action owner <record_uid>

Share folder (grant)

share-folder --email <email> --action grant --manage-records {on|off} --manage-users {on|off} [--expire-in <ttl>] <folder_uid>

Share folder (remove)

share-folder --email <email> --action remove --manage-records off --manage-users off <folder_uid>

Nested share record

nsf-share-record

Nested share folder

nsf-share-folder

One-time share

one-time-share create --expire <ttl> [--editable] <record_uid>

Approve device

device-approve <email_or_device_id> {--approve|--deny}

Approve EPM

epm approval action {--approve|--deny} <request_uid>

Vault search (records)

search <terms> --format json -c r

Vault search (folders)

search <terms> --format json -c s -c d

Flag semantics: Sharing Commands reference.

Error Handling

Condition
App behavior

ServiceMode unreachable on install

Install fails with a message to verify host and API key

Invalid email, permission, decision, or expiration

Returns INVALID_INPUT; agent sees a validation message

ServiceMode HTTP 401 / 403

Returns UPSTREAM_AUTH — verify or rotate the API key in app settings

ServiceMode request expired or poll timeout

Returns UPSTREAM_TIMEOUT

ServiceMode failed, 4xx / 5xx, or inner Commander error

Returns UPSTREAM_FAILED with Commander's error message

Commander rejects OTS on unsupported record type

UPSTREAM_FAILED with Commander's verbatim message

Request already processed in Keeper

Sidebar shows processed state; no duplicate action

Testing the Configuration

Test
Expected result

App install

Succeeds; ServiceMode health check passes

Service catalog item

Request Keeper Vault Access published with request_type dropdown (manual admin setup)

Vault search

Returns records or folders for a known query (≥ 2 characters)

Approve Record Access

Recipient receives vault access; optional Activity note

Approve Folder Access

Recipient receives folder access

Approve One-Time Share

Share URL returned in sidebar

Deny request

Justification note on ticket Activity (if API key configured)

Approve EPM / device

Commander completes; ticket shows processed state

Invalid API key

UPSTREAM_AUTH on fulfillment attempt

Troubleshooting

Install fails — ServiceMode unreachable

  1. Confirm ServiceMode Host has no https:// prefix and no path.

  2. Confirm ServiceMode is running and listening on HTTPS.

  3. Confirm the host is reachable from the public internet (not only internal network).

  4. Check firewall, reverse-proxy, and TLS certificate configuration.

Install fails — authentication error

  1. Regenerate the ServiceMode API key.

  2. Re-enter the key in Admin → Apps → Keeper Security Workflow → Settings.

  3. Confirm the key has permissions for the required Commander commands.

Keeper sidebar not shown on a vault access ticket

  1. Confirm the service catalog item is published and the ticket came from that item.

  2. Confirm the item name or description includes a Keeper vault access phrase (for example Request Keeper Vault Access).

  3. Confirm the request_type dropdown uses Record Access, Folder Access, or One-Time Share Link.

  4. If the ticket sidebar tab is missing on your tenant, open the app from the Apps launcher (full-page entry point).

  5. See Step 3 — Service catalog setup for the full admin checklist.

UPSTREAM_AUTH when approving

  1. Open app settings and verify the ServiceMode API key.

  2. Rotate the API key on the ServiceMode host and update app settings.

Sidebar tab not visible on tickets

  1. Some Freshservice tenants (sandbox, trial, certain plans) do not render ticket_sidebar reliably.

  2. Open the app from the Apps launcher instead (full-page entry point, same UI).

  3. Confirm the app is installed and enabled under Admin → Apps.

Ticket shows "not a Keeper vault access or approval request"

  1. Confirm the ticket is a Keeper catalog request or an ITSM-generated EPM / device ticket.

  2. For vault access, verify the request type is Record Access, Folder Access, or One-Time Share Link.

  3. For EPM / device, confirm keeper_request_id is populated by the ITSM app.

Vault search returns no results

  1. Confirm the ServiceMode service account can run sync-down and search.

  2. Use at least 2 characters in the search query.

  3. Confirm the record or folder exists in the vault visible to the ServiceMode account.

Vault search shows an unexpected error

  1. Confirm ServiceMode is running.

  2. Check ServiceMode logs for Commander errors.

  3. Verify supported commands include search and sync-down.

Approve succeeds but no Activity note

  1. Configure the Freshservice API Key in app settings.

  2. Confirm the key belongs to an admin account with permission to add ticket notes.

  3. Without the API key, Keeper fulfillment still runs; only ticket notes are skipped.

EPM or device requests not appearing

  1. Confirm Keeper Security ITSM for Freshservice is installed and configured.

  2. Confirm EPM and device alerts are enabled in Keeper Admin Console → Reporting and Alerts.

  3. Confirm the webhook URL and token match the ITSM app configuration.

  4. Verify a test alert creates a ticket with keeper_request_id.

One-time share fails with Commander error

  1. Confirm the record type supports one-time shares.

  2. Confirm the record UID is valid and not expired.

  3. Surface error.message from the app response to the agent — the app returns Commander errors verbatim.

Request already processed outside Freshservice

If a request was approved or denied directly in Keeper Admin Console or Commander, the sidebar shows a processed state and does not re-submit the action.

Related Documentation

PreviousFreshService ITSM
NextGit - Sign Commits with SSH

Last updated

Was this helpful?