Authenticated Remote Search Links

You can use an authenticated remote search link to send an external user directly to the results of a predefined Keep search from an external system, such as a customer portal or ERP.

The external user does not need to log in, and their view is restricted to search only.

The link can be reused until it expires or you revoke it. Each use creates a fresh search and follows Keep's normal browser-session timeout.

Prerequisites

Before creating a link:

1. Create a dedicated, non-administrator Keep user for your integration. This user is separate from the external users who will eventually redeem the resulting links.

2. Grant that user the minimum necessary permissions to log in and use the search configuration.

3. Assign the named search configuration to that user.

4. Generate an API key assigning that user as the Run As Identity in the Generate New API Key window (see REST API Authentication).

5. Store the generated key in your integration's backend secret store, environment, or protected configuration. Do not share it.

Note

You cannot create remote search links using an API key with an administrator run-as identity.

Configure the Link Lifetime

The server setting general.remote-search-link-lifetime-days controls how long newly created links remain valid. The default is 30 days.

Each link receives an absolute expiry time when Keep creates it, so changing this setting affects only links created afterward. You cannot request a different lifetime for an individual link.

Create a Link

Send a server-to-server request to:

POST /rest/v1/applications/remote-search-launch/{searchName}
DM-API-KEY: <api-key>
Content-Type: application/json

The request body must contain a fields object, whose property names are the search configuration's query field names and whose values are strings in the format each field expects. Always send the fields object, even when the search configuration's defaults are sufficient ({"fields": {}}).

For example:

curl --fail-with-body \
  --request POST \
  "https://KeepServer/rest/v1/applications/remote-search-launch/all-documents" \
  --header "DM-API-KEY: <api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": {
      "customer-number-1": "43679"
    }
  }'

A successful request returns 200 OK with the created link's id, launchUrl, and expiresAt. Store id only if you might need to revoke this specific link later. Send only launchUrl to the external user, and treat it as a bearer credential: never log it, the API key, or the field values.

Keep rejects unknown fields, read-only fields, null values, and values that cannot be converted to the field's configured type.

Open a Link

The external user cannot open a remote search link while another Keep session is already active in that browser. They must log out first, or use a fresh or private browser session.

The named search configuration runs automatically with the stored field values when the link is opened. The external user sees a restricted interface: search results, document viewing, and permitted downloads are available, but search criteria, editing controls, notes, sharing, quick navigation, and the account menu are all hidden. The Keep logo is not clickable.

The link can be reused from a new anonymous session until it expires or you revoke it.

Revoke a Link

Revoke a Single Link

Use the id that Keep returned when it created the link:

DELETE /rest/v1/applications/remote-search-launch/{id}
DM-API-KEY: <originating-api-key>

Only the API key that created a link can revoke it through this endpoint. Keep reports an unknown ID, a malformed ID, or an ID belonging to a different key as not found. A successful revocation returns 204 No Content and does not affect any other links created by the same key.

Revoke Every Link from an API Key

Delete the API key itself (User Management > API Keys). Deleting the key deletes all launch grants created by it, so every link it created stops working. This does not revoke links created by other keys.

When a Link Stops Working

Keep revalidates a link's grant each time the external user redeems it. A link becomes unavailable, for example, when:

• It has expired, or you have revoked it.

• Its originating API key no longer exists.

• Its run-as identity is disabled, deleted, no longer permitted to log in, or is now an administrator.

• The named search configuration no longer exists, or is no longer assigned to the run-as identity.

Creation requests commonly fail with:

Revocation requests return 401 Unauthorized for an invalid API key, and 404 Not Found if the link cannot be found for the originating key.

Security Guidance

• Treat the link URL as a bearer credential: anyone who has it can use it until it expires or you revoke it.

• Use HTTPS outside local development.

• Keep the API key in backend-only secret storage; never send it to a browser.

• Do not log API keys, link URLs, or field payloads.

• Send links only through an appropriately protected channel.

• Use a dedicated, least-privileged run-as identity, and review its permissions regularly. The restricted interface the external user sees is a presentation safeguard, not a substitute for it. The resulting browser session still carries the run-as identity's real server-side permissions.

• Revoke a link once the external user no longer needs it, if it does not need to stay available for its full configured lifetime.

• Remember that this API key is a normal Keep API key, not one scoped only to remote-search operations. It can call any REST operation that its run-as identity is permitted to.

This replaces the legacy Remote Document Search mechanism.