Skip to main content
Tool Gateway is in beta.
The credential a caller sends to Tool Gateway decides whose connected accounts each tool call uses. A product that serves many end users can call tools as each user, with that user’s own accounts. An agent that runs with no one signed in can call tools with its own credentials or with a shared profile. For how this layer fits with the other two layers of authentication, see How Tool Gateway works. This page covers the caller side: what to send on each request. To connect the accounts that a user, an agent, or a profile calls with, see Connect accounts.

Choose a credential

A service key can list servers and call tools, but it cannot create servers or tool kits, or connect credentials for another owner. Use a personal access token for those. For the difference between key types, see API keys. Each call acts as one identity. A request that names more than one, such as X-LangSmith-Profile together with X-LangSmith-Identity or an end user’s token, is rejected with 400.

Call as yourself

To call tools with your own connected accounts, send your personal access token in X-Api-Key. No other header is needed. This is how the quickstart and MCP clients call Tool Gateway.
A personal access token always acts as its owner. Tool Gateway ignores X-LangSmith-Identity on a request authenticated as a user.

Call as your end users

If your product calls tools for many end users, each call can run as that user, with the accounts the user connected. Pick one of three patterns. Two of them use access tokens from your company’s identity provider, such as Okta or Microsoft Entra ID. Those two require a workspace admin to link the identity provider first. A service key that acts for end users needs the workspaces:credentials:use or agent-auth-credentials:use permission. The Workspace Admin role and deployment runtime keys carry one of them. A key without either permission gets 403. The first time a user calls a server they have not connected, the call returns a sign-in link instead of running. Pass the link to the user, then retry the call after they connect. See When the caller is a user. Linking an identity provider lets Tool Gateway accept access tokens that the provider issues, and match each token to the user it names. A workspace links one identity provider. Linking an identity provider requires the workspaces:integrations:manage permission and a personal access token or LangSmith session, not a service key. To link an identity provider:
  1. Go to Tools, and click Configure OIDC.
  2. In the Identity provider dialog, choose an existing provider and click Link, or add a new one:
    • Display name: A name for the provider, such as Okta.
    • Slug: A short identifier, such as okta.
    • Issuer: Your provider’s issuer URL. Tool Gateway matches it against the iss claim of each token.
    • Audience: The audience your provider issues the tokens for.
  3. Click Add and link.
To remove the link, open the same dialog and unlink the provider. Tokens from the provider stop working on the next call.

Send a user token with a service key

Use this pattern for a backend that serves many users. Keep one service key on your backend, never in a browser, and send each end user’s access token alongside it. Tool Gateway verifies the token against the linked identity provider, and the call runs as the user the token names.
Send exactly one Authorization header. A token that the linked provider did not issue, or that has expired, returns 401. Do not send X-LangSmith-Identity on the same request.

Name the user from your backend

If your backend already knows who the user is, send a service key and name the user in the X-LangSmith-Identity header. Use this pattern when your users do not sign in through an identity provider that you can link.
The value is provider:user-id, such as gtm:user-123, or a user’s principal ID from Agent Auth. Each distinct value is a separate user, with separate connected accounts.
Tool Gateway trusts the X-LangSmith-Identity value as sent. Any caller that holds the service key can act as any user. Send the header only from a backend you control, and never expose the service key to a browser or an end user.

Send only a user token

A user or app can call a tool kit or a server with only the user’s access token, and no LangSmith key. Send the token as the request’s only credential:
This pattern has limits:
  • It works only for MCP calls to a tool kit’s or a server’s endpoint, not for the management API.
  • It does not work on the me kit, because the me kit belongs to no single workspace.
  • A call to a built-in server’s endpoint must also send X-Tenant-Id, so Tool Gateway knows which workspace’s identity provider to check.
A caller authenticated only by an identity provider token can reach any server or tool kit in the workspace. Through a kit, it reaches only the tools that kit includes. Control access through which users and apps your identity provider issues tokens to, and use policies to restrict what those callers can invoke.

Call as an agent

A deployed agent can call tools as itself, with credentials an admin connected for its agent environment. Send an API key bound to that agent environment. Tool Gateway recognizes the key and uses the agent’s credentials, with no extra header.
The key also needs the workspaces:credentials:use or agent-auth-credentials:use permission. Because each agent environment holds its own credentials, an agent’s development and production environments can call the same server with different accounts. To connect the agent’s credentials, see Connect an account for an agent. An agent cannot connect its own accounts, because no one is present to sign in. A call to a server the agent has not connected returns 409, and a workspace admin must connect it. If a request with an agent key also sends X-LangSmith-Profile or names an end user, that identity is used instead of the agent’s.

Call with a profile

A profile is a named set of credentials that a workspace admin connects once. Use a profile for an agent, scheduled job, or deployment that runs with no one signed in. Examples include a nightly reporting agent and a coding agent that works from a shared GitHub account. Add the profile’s ID in the X-LangSmith-Profile header:
To copy the header from the UI, set Connected as to Profile on Tools > MCP servers, select the profile, and click Copy profile header. To list profile IDs with the API, send GET /v1/managed-tools/profiles. Using a profile requires the workspaces:credentials:use or agent-auth-credentials:use permission. A workspace admin, a service key with the Workspace Admin role, and a deployment runtime key all qualify. Other keys get 403. A profile works only with workspace tool kits and workspace servers, not personal ones. A call to a server the profile has not connected returns 409, and a workspace admin must connect it.

Fix identity errors

The errors in this table come from how a request names its identity. For other errors, see Errors.

See also