Skip to main content
By default a call made with a member’s API key runs as that member, whatever user the request names. When your own app calls an agent for people who are not members of your organization, turn on API callers name the end user on the agent: in xpander Chat, open the agent’s Channels; the switch is in the API section, under Developer access (which must be on). Over the API, set api_callers_name_end_user: true in Update Agent.
API section of the Channels pane: Developer access switched on, the API endpoint with Open API keys and Create API key for this agent, then the API callers name the end user switch, Public webhook URLs and Ticket triggers

The API section of an agent's Channels, with Developer access on and the API callers name the end user switch below the API endpoint. Shown with sample data.

With it on:
  • The user you name runs as a separate end user, with their own memory, conversations and sign-ins. On the API that is input.user (email is required). On the webhook it is user_id or user_email. That end user is never one of your organization’s members, even when the id or email matches one.
  • With no token in Authorization, the person the request names runs as an end user that xpander has not verified.
  • An end user can only continue their own conversations. Continuing another person’s conversation (id on the API, task_id on the webhook) answers 403.
  • When the call carries the user’s identity provider token in Authorization: Bearer <token>, xpander verifies it with your organization’s identity provider (the one set up for SSO). A verified token whose email belongs to a member runs as that member; any other verified token runs as the end user the token names. A token the identity provider rejects answers 401; if xpander cannot reach the identity provider, the call answers 503.
  • Calls made with the organization’s default API key are unchanged: they run as whoever the request names.
With it off, a member’s API key that names a different user answers 403.

Call the agent

The webhook takes the same header:
On a self-hosted install, use your own API and webhook hosts.

Pass the user’s tokens to MCP skills

There are three ways the user’s token reaches an MCP skill. You can mix them on one agent.
  • user_tokens: a token per skill, keyed by the skill’s id on the agent (the id field in tools from Get Agent, not mcp_id). A string value is sent as Authorization: Bearer <value>; an object value is sent as the request headers. A key that matches no skill is ignored, and that skill falls back to its own sign-in.
  • Skills set to Signed-in user (SSO): in the skill’s form, Authentication is Signed-in user (SSO) and Token sent picks the mode. On an agent with API callers name the end user on, a verified token in Authorization reaches each of these skills in that mode: as is (Access token), or exchanged for the Audience you set (Exchange for an audience). A user_tokens entry for the skill wins.
    MCP skill form with Authentication set to Signed-in user (SSO), Token sent options Access token, ID token and Exchange for an audience, and the Audience field set to api://inventory

    An MCP skill signed in as the Signed-in user (SSO), with Token sent set to Exchange for an audience and its Audience filled in. Shown with sample data.

  • Identity provider pre-authentication on the agent: the exchanged token goes only to skills with Send the user’s identity provider token turned on. The switch is in the skill’s Edit form on the agent, shown when the agent uses identity provider pre-authentication and the skill’s Authentication is not Signed-in user (SSO). Over the API it is use_pre_auth_token: true in the add-skill API. Skills that were on the agent before this setting existed keep receiving it. Where this token applies, it is used instead of that skill’s user_tokens entry.
    Edit form of an MCP skill using OAuth2, with the Send the user's identity provider token switch turned on above Health check

    An MCP skill's Edit form on an agent, with Send the user's identity provider token turned on. Shown with sample data.

Before you turn it on

  • Token checks use the identity provider set up for SSO. Your users’ tokens must come from that issuer, and its discovery document, JWKS and userinfo endpoints must be reachable from xpander (on a self-hosted install, from the pods).
  • To exchange a token for a skill’s audience, your identity provider must allow token exchange for that audience on the client you set up in xpander.
  • Turn it on only on agents your own app calls for end users.