Tools Connected to External Services

When building automations or AI agent actions that integrate with external services (e.g., Google Sheets, custom APIs), it is important to strictly protect your organization’s internal data and user privacy.

Tools often operate outside your secure environment, so you must take extra care to ensure that only the correct contact’s data is accessed and no organization-wide confidential information is ever exposed.

Do Not Reveal Sensitive Information

When using external-service tools, avoid exposing:

• Internal or proprietary system data

• Organization-wide confidential details

• Other users’ or contacts’ personal information

• Any information not specifically owned by the current contact

Tools should act only on data belonging to the contact currently in session.

Scope Every Action to a Single Contact

To prevent data leakage, all tool calls must be scoped to the currently authenticated contact.

Depending on the type of tool, the scoping mechanism differs:

1. App Tools

Apps authenticated via OAuth, such as Google Drive, Google Sheets, Outlook, etc.

For App Tools, use: {{data.contact.externalId}} placeholder in mustache field.

This placeholder provides the current contact’s external ID, assigned during custom sign in.

Example

When using the Google Sheets App Tool, you may ensure each row belongs to the current contact by Read or write only when Column A matches {{data.contact.externalId}}.

This enforces a “per-contact boundary” inside Google Sheets or any similar external data source.

2. OpenAPI Tools

Custom API calls using your own backend endpoints

For OpenAPI Tools, you may validate the contact by reading the request header: X-Contact-External-Id.

To protect your endpoint from unauthorized calls (bots, external attacks, or clients hitting your endpoint directly), you should require an additional secret header such as x-knoon-api-secret.

Your backend should verify:

• The header exists.

• The header value matches the externalId previously provided to you during custom sign in.

• Reject the request if it is missing or incorrect

• The secret value matches your stored server secret

• Rejects requests with missing/invalid secret

Example

GET /customer/orders
X-Contact-External-Id: 12345-abc

On your backend:

const apiSecret = req.headers['x-knoon-api-secret'];

if (!apiSecret) {
  return res.status(400).json({ error: 'Missing X-Knoon-API-Secret header' });
}

if (apiSecret !== process.env.KNOON_API_SECRET) {
  return res.status(403).json({ error: 'Invalid API secret' });
}

const externalId = req.headers['x-contact-external-id']
if (!externalId) {
  return res.status(400).json({ error: 'Missing X-Contact-External-Id header' })
}

// An example on to retrieve contact from your backend
const user = await getUser(externalId)

if (!user) {
  return res.status(404).json({ error: 'Contact not found' })
}

This prevents unauthorized users from accessing other contacts’ data.

NOTE

Change (rotate) your secret regularly and update the secret in your Knoon tool configuration.

Why This Matters

Without proper scoping:

• Cross-contact data leaks may occur.

• Agents may unintentionally reveal sensitive records.

• OAuth integrations (Sheets, Drive, etc.) may process data for the wrong person.

• API endpoints may expose entire datasets if not protected.