---
title: "Filter API calls by the person using the tool: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/connection-functions/
updated: 2026-11-21
---

# Function in front of a connection

You place a function, written with your AI, in front of the connection to an API. Before each call from a tool, it sees the request and the person using the tool, verified by while. It denies the call, or sends it on as is or modified.

> You, to your AI: Make sure each person only sees the sales of their own branches in our API.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
apiVersion: while/v1
project: sales-gateway
functions:
  - name: scope
    connection: sales
    file: scope.js
    timeout_ms: 300
```

## When to use it

Use it when what a call is allowed to do depends on the person using the tool, for example when each person must only see their own branches.

## How it works

You place a JavaScript function, written with your AI, in front of the connection to an API. Before each call a tool makes to that API, the function receives the request and the person using the tool, verified by while, then denies the call or returns the request to send.

## What to know

A new version only serves once it has been approved by a person who can configure the connection, never by an AI. Until then, the previously approved version keeps serving, and going back to a version already approved needs no new approval. As long as no version is approved, every call to the connection is refused (503, function-not-validated).

The timeout is 300 ms by default and 2 s at most (`timeout_ms`), for onRequest and for onResponse alike. The request body is read as JSON, up to 1 MiB: beyond that, or in another format, body is null and bodySize gives its size. A response reviewed by onResponse is JSON and 2 MiB at most: any other is refused (502, function-response), except an error from the API, which goes back as is. An organization has 10 functions at most: beyond that, the deployment is refused. A connection has only one function in the organization, declared by a single project: an unknown connection, or one whose function another project already declares, also gets the deployment refused.

Write a deny message that says what to do: it reaches the tool and its AI as is, with its status (403 by default, from 400 to 499) and the code "function". Any result other than a send or a deny is also a refusal: function-error (502) for an exception, a malformed result or a function that is down, function-timeout (504) for a timeout.

The function sees neither the API key, added after it, nor cookies, nor Authorization, nor the `X-While-Identity` token itself. It cannot reach the Internet, and its request always goes to the connection's host. `{ send: request }` also sends the API the headers set by the tool: a header the API trusts must therefore be written by the function, which overwrites the tool's. The tool's access to the connection is still checked. With read access only (connection-caller role), nothing gets through but GET, HEAD and OPTIONS, and the POSTs the function returns with read: true. A tool that writes through the function needs write access (connection-writer role). Behind the function, the connection does not apply its rules and no longer learns from calls: the function decides.

person is null for a scheduled task, for a visitor who came through a share link, and when the tool did not forward `X-While-Identity`. The tool can neither choose the person nor change their kept claims (`person.claims`): they are not in `X-While-Identity`, they are re-read on while's side. However, as long as a person is using the tool, and up to 5 minutes after their last request, it can call the API with their identity, for everything the function allows it.

A person's scope, their branches for example, dates from the moment they signed in (`signed_in_at`), 8 h ago at most. What is taken away from them at your identity provider leaves their scope when they sign in again.

With inspectResponse: true, the response is read in full before it goes back, with no streaming, and the data has already left the API when the function reads it. Removing rows breaks the API's pagination and totals: enforce the filter in the request instead, and keep onResponse for masking a field or checking a single record.

Every decision is recorded in the connection's call log, without the body.

## Your agent's MCP tools

Your agent handles it with the `try_connection_function`, `list_connections` and `call_connection` tools.
