Skip to main content

Delegation — running on behalf of the calling user

Some pipelines exist to serve a specific person in the moment: the clearest example is an application's AI chat, where a user types a question and a pipeline answers it by looking up data. For flows like this it would be wrong for the pipeline to use its own broad service account — the user must only see their own data, exactly as they would elsewhere in the application.

Delegation solves this. In delegation mode a pipeline carries out its work under the calling user's identity instead of its service account's. The user sees precisely the data they are allowed to see — and this is enforced on the server by data permissions, not by hiding things in the user interface.

Effective roles are the intersection​

A delegated run is deliberately limited to what both sides may do. The effective roles are the intersection of the service account's roles and the user's roles:

effective roles = service-account roles  ∩  user roles

This has two consequences worth remembering:

  • A powerful service account can never grant a user more than the user already has. Acting for a low-privilege user gives you the low-privilege set.
  • If the two role sets do not overlap at all, the delegated identity has no roles — a valid outcome that simply sees nothing. This is not an error; it is the safe default. (A common cause of "the chat returns nothing" is a service account that lacks the role the feature needs — see below.)

The underlying OAuth mechanism (an on-behalf-of grant, same-tenant only, no refresh tokens) is described in Authentication → Delegation / On-Behalf-Of.

How to enable it​

Delegation is switched on per flow with two small pieces.

1. A token-carrying HTTP trigger — FromHttpRequest@2​

The pipeline must be triggered in a way that carries the caller's identity. The FromHttpRequest@2 trigger does exactly this: it requires a valid access token on the incoming request and makes the caller's identity available to the rest of the pipeline. Its requiredRoles list gates who may call the endpoint at all — any one of the listed roles is sufficient, and an empty list accepts any caller with a valid token.

triggers:
  - type: FromHttpRequest@2
    path: /aiPrompt
    method: POST
    requiredRoles:
      - AccountingManagement
      - AccountingEmployee

2. Delegation on the AI node — mcpDelegateToCaller​

On the AI node (AnthropicAiQuery@1), set mcpDelegateToCaller: true. The node's MCP tool calls (the lookups the AI performs to answer the question) then run under the caller's delegated identity rather than the service account's.

transformations:
  - type: AnthropicAiQuery@1
    path: $.question
    targetPath: $.answer
    apiKeyConfigurationName: AnthropicAiConfig
    mcpServiceAccountConfigName: PipelineServiceAccount
    mcpDelegateToCaller: true          # run the MCP lookups as the calling user
    mcpToolNames:
      - query_entities_simple
    question: "Answer the user's question using the available data."
info

Delegation is fail-closed. If mcpDelegateToCaller is set but no caller token is present (for example the pipeline was started from a scheduler, or from the editor's Run button, which do not carry a user token), the node refuses rather than silently falling back to the service account. Test delegated flows over HTTP with a real bearer token.

What the service account still needs​

Even in delegation mode the service account matters, because the effective roles are an intersection with it. The service account must itself carry the roles the feature relies on — otherwise the intersection is empty and the user sees nothing regardless of their own roles.

A practical rule: give the delegating service account the same functional roles the feature's users have (for the AI chat example, the accounting roles). The intersection then narrows each user down to their own subset, which is exactly the goal.

A worked example: the application AI chat​

The accounting application's "ask a question about my documents" chat is built this way end to end:

  1. The app calls the aiPrompt pipeline over HTTP, forwarding the signed-in user's token.
  2. FromHttpRequest@2 requires that token and gates the call on the accounting roles.
  3. The AnthropicAiQuery@1 node runs with mcpDelegateToCaller: true, so its data lookups run as the user.
  4. Two different users asking "how many documents can I see?" get different, correct answers — a manager sees all documents, an employee sees only the ones they own — without any per-user configuration in the pipeline. The difference comes entirely from their roles and the tenant's data permissions.