Authenticate to the LLM Gateway

Every request to the LLM Gateway authenticates with a LangSmith API key, never with a model provider’s key. This page covers which key to use, the permission it needs, and how each client sends it.

​

Understand the two layers

A gateway request passes two separate authentication checks:

• Your client to the gateway: your code sends a LangSmith API key, which starts with lsv2_. The gateway checks the key’s permissions, then applies your organization’s policies.
• The gateway to the provider: the gateway calls the model provider with a credential stored in LangSmith, usually a provider API key saved as a workspace secret. Your code never holds this credential. For the credential types each provider accepts, see Provider authentication.

​

Choose a key type

Two kinds of LangSmith API key can call the gateway:

• Personal access token (PAT): prefixed lsv2_pt_. A PAT carries the permissions of the user who created it. The Simulator’s Create Gateway Key button creates a PAT.
• Service key: prefixed lsv2_sk_. A service key belongs to the organization rather than a user. On the Enterprise plan, you can assign a service key its own workspace role.

​

Grant permission to call the gateway

To call the gateway, an API key needs both gateway:invoke and workspaces:read in the workspace it belongs to. A PAT has these permissions when its user’s role does. Which roles include them depends on your plan:

• Plans without workspace roles: every user has the Workspace Admin role, which includes both permissions. No setup is needed.
• Enterprise plan: the Workspace Admin role includes both permissions. The built-in Workspace Editor and Workspace Viewer roles include neither, and built-in roles cannot be edited. To grant gateway access without full admin rights, create a custom role with gateway:invoke and workspaces:read, and assign it to the users who call the gateway.

For a service key with its own role, grant the same two permissions to that role. A service key whose role lacks gateway:invoke gets a 403 with missing permission gateway:invoke.

​

Use a workspace-scoped key

Use a LangSmith API key scoped to one workspace. That workspace determines which provider secrets the gateway reads, which policies apply, and where traces land. For a PAT, this is the key’s default workspace. A key created in the Simulator belongs to the workspace that was open when you created it. Organization-scoped keys are not supported for gateway requests.

​

Send the key

The gateway accepts the key in any of these headers:

• Authorization: Bearer <key>
• X-Api-Key: <key>
• X-Goog-Api-Key: <key>

Each client sends its API key in one of these headers, so you set the key where the client expects its provider key: Claude Code with a Claude subscription is the exception: its Authorization header carries the Anthropic OAuth token, so it sends the LangSmith API key in X-Api-Key through ANTHROPIC_CUSTOM_HEADERS. For base URLs and request examples, see API formats and Direct model access.

​

Set environment variables

LangChain chat models and Deep Agents read the key from the environment:

• LANGSMITH_API_KEY: the LangSmith API key, also used for tracing.
• LANGSMITH_GATEWAY: set to true to send supported chat models through the gateway. For details, see Direct model access.
• LANGSMITH_GATEWAY_API_KEY: an override for gateway requests when they need a different key from LANGSMITH_API_KEY. It must meet the same requirements: workspace-scoped, with gateway:invoke.

Deep Agents Code requires LANGSMITH_GATEWAY_API_KEY, even when it holds the same key as LANGSMITH_API_KEY. With only LANGSMITH_API_KEY set, it stops at startup with No credentials found for provider.

​

Fix authentication errors

For a 424, an error that shows a masked provider key, or an Anthropic invalid x-api-key when your base URL already points at the gateway, the problem is the provider key stored in LangSmith, not your API key. See Fix provider credential errors. Requests that a policy blocks return 402 for a spend limit and 429 for a rate limit. The response body names the policy, for example {"type":"error","error":{"message":"request blocked by gateway policies: <POLICY_NAME>"}}.

​

See also

• Provider authentication: store the credentials the gateway uses to call each provider.
• Set up the LLM Gateway: set up provider keys, permissions, and policies for your organization.
• Create a LangSmith API key: create a PAT or service key.

---