Acting as your site's user

How it works

1. Before each message, the chatbot asks your page for the signed-in user's token (getSubjectToken) and sends it to Squadico.
2. Squadico exchanges that token at your authorization server for a new one: same user, meant for the connector alone. This is the OAuth 2.0 Token Exchange standard (RFC 8693), or the on-behalf-of flow (RFC 7523) for Microsoft Entra ID.
3. Squadico calls the connector with the new token. Your site's token is never sent to the connector, nor kept.
4. The connector checks the token and calls your API as the user, ideally through its own token exchange.

What you need

• An OAuth authorization server that can exchange tokens (RFC 8693) or do on-behalf-of.
• A Squadico application with identity verification on: the token is only accepted for a visitor whose identity your server signed (digest).
• An MCP connector that accepts tokens issued by that authorization server.

1. In your identity provider

Three things, whatever the provider: a confidential client for Squadico allowed to exchange tokens; a recipient (audience) standing for the connector; and, with some providers, the Squadico client in the audience of your site's tokens.

2. In Squadico

1. Settings → your organization → Tools → the connector → Configure OAuth: your authorization server's authorization and token URLs (if they were not discovered), the Squadico client's id and secret.
2. Add the Squadico callback URL to the client's redirect URIs: the organization's authorization uses it.
3. Authorize the connector once as the organization: that token only reads the tool list, never calls a tool.
4. Identity used for calls → "The user of the site hosting the chatbot", then set up the exchange (see the table).

Exchange settings

3. On your site

Turn on the application's identity verification, compute the user's digest on your server, and give the chatbot a function returning the current token. It is called before every message: return a fresh token, or null when nobody is signed in.

// On your server, when the page is rendered — never in the browser
const digest = createHmac('sha256', process.env.SQUADICO_IDENTITY_SECRET)
  .update(user.id)
  .digest('hex')

// In the page
const chatbot = document.querySelector('squadico-chatbot')
chatbot.user = { id: user.id, name: user.name, digest }
// Called before every message: return the current token, refreshed if needed
chatbot.getSubjectToken = () => auth.getAccessToken()

4. On your MCP connector

• Check the token's signature (your authorization server's public keys), its issuer (iss) and that its audience (aud) names the connector.
• sub is the user; azp (or appid) names Squadico, which helps trace or restrict what an agent does.
• To call your API, make your own token exchange towards the API's audience rather than forwarding the token received: the MCP specification advises against forwarding a token as is.

Testing

Get a token for a user of your site, then make the exchange Squadico will make. The token you get must carry the same sub and the connector's audience. You can then paste the original token in the "Test user token" field of your application's sandbox.

TOKEN_URL=https://<your-idp>/…/token

# The exchange Squadico makes (RFC 8693, HTTP Basic client authentication)
curl -s "$TOKEN_URL" \
  -u "<squadico-client-id>:<squadico-client-secret>" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token="$USER_TOKEN" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d audience=<connector-audience> \
  -d resource=<connector-url>

# Expect a token with the same "sub" and the connector in "aud"

Troubleshooting