Tool Gateway is in beta.
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 inX-Api-Key. No other header is needed. This is how the quickstart and MCP clients call Tool Gateway.
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 theworkspaces: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.
Link your identity provider
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 theworkspaces:integrations:manage permission and a personal access token or LangSmith session, not a service key.
To link an identity provider:
- Go to Tools, and click Configure OIDC.
- 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
issclaim of each token. - Audience: The audience your provider issues the tokens for.
- Display name: A name for the provider, such as
- Click Add and link.
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.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 theX-LangSmith-Identity header. Use this pattern when your users do not sign in through an identity provider that you can link.
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.
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:- 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.
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.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 theX-LangSmith-Profile header:
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
- Connect accounts
- Call tools through Tool Gateway
- How Tool Gateway works
- Set policies
- Agent environments
Connect these docs to your agent of choice via MCP for real-time answers.

