Acting for end users - NeuralTrust Docs | TrustGate, TrustGuard, TrustTest

The same key and the same application serve two actors. Without a name, a call runs as the application itself. With one, it runs as that person, and each upstream server that keeps an account per user reaches for theirs. Naming the person is a per-call decision, not a setting:

from trustgate import ConsentRequiredError, ToolFormat

alice = tg.for_end_user("user_123")

try:
    alice.toolkit(ToolFormat.OPENAI_RESPONSES).execute(response.output)
except ConsentRequiredError as e:
    reply(f"I need access to {e.provider}: {e.connect_url}")

import { ConsentRequiredError, ToolFormat } from "@neuraltrust/trustgate"

const alice = await tg.forEndUser("user_123")

try {
  await alice.toolkit(ToolFormat.OpenAIResponses).execute(response.output)
} catch (error) {
  if (error instanceof ConsentRequiredError) {
    reply(`I need access to ${error.provider}: ${error.connectUrl}`)
  }
}

An Agent from connect() gives the same handle with agent.for_end_user(…) (forEndUser(…)), without another round trip: the tool set an admin bound is the application’s, identical for everyone it acts for. What changes is one header, X-NeuralTrust-End-User.

No startup check, a link instead

connect() refuses to start when a server has no account, because a batch has nobody to send a link to. A person does, so for_end_user() does not check at startup. When a call needs an account the user has not connected, the gateway refuses it with ConsentRequiredError, and the link to connect arrives inside the error, because that is where the gateway mints it. When you would rather ask than fail, check ahead of time:

for connection in alice.connections():
    print(connection.provider, connection.status)

link = alice.connect_link("com.notion/mcp")  # omit the provider to cover every server
send(link.connect_url)                        # it expires: mint it when you show it

for (const connection of await alice.connections()) {
  console.log(connection.provider, connection.status)
}

const link = await alice.connectLink("com.notion/mcp") // omit the provider to cover every server
send(link.connectUrl)                                  // it expires: mint it when you show it

Whose name it is

The name is yours to choose, and the gateway does not verify it: it trusts the application that holds the key. Whoever holds the key can name anyone, and a call that names a person reaches the accounts that person connected through this application. So the key is the identity check: run the SDK where only your backend holds it, and take the name from the session your backend already authenticated, never from what the client sends.

alice = tg.for_end_user(session.user.id)  # your backend decides who this is

const alice = await tg.forEndUser(session.user.id) // your backend decides who this is

Three setups break this:

One key, many people. The key in each person’s script, notebook or desktop agent, each passing their own name: any of them can pass someone else’s and use the accounts that person connected.
A name taken from the request. for_end_user(request.json["user_id"]) lets any user of your product send another user’s id.
A leaked key. Whoever has it can act as every person the application names, and can connect their own account under someone’s name, so that person’s calls land in it.

For people who use their own tools from their own client, use TrustGateUser: their personal key or sign-in is verified, and their accounts follow them.

The name is namespaced by application, so two applications naming user_123 never reach the same account, and the accounts a person connected in the Employee portal are never reachable by name. For the same reason only an application’s own credential may assert one: a request carrying a person’s own token is already that person. This is the code side of acting for end users on the gateway.

​No startup check, a link instead

​Whose name it is

No startup check, a link instead

Whose name it is