Set up Agent Auth

Enable secure access from agents to any system using OAuth 2.0 credentials with Agent Auth.

Agent Auth is in beta and under active development. To provide feedback or use this feature, reach out to the LangChain team.

Installation

Python

pip

pip install langchain-auth

uv add langchain-auth

JavaScript

npm install @langchain/auth

Quickstart

1. Initialize the client

Python

from langchain_auth import Client

client = Client(api_key="your-langsmith-api-key")

JavaScript

import { Client } from '@langchain/auth';

const client = new Client({ apiKey: 'your-langsmith-api-key' });

Self-hosted configuration

For self-hosted LangSmith instances, specify the API URL using the /api-host path on your instance.

Environment Variable

export LANGSMITH_API_URL="https://your-langsmith-instance.com/api-host"

Then initialize the client normally:

client = Client(api_key="your-langsmith-api-key")

Explicit Configuration (Python)

client = Client(
    api_key="your-langsmith-api-key",
    api_url="https://your-langsmith-instance.com/api-host"
)

Explicit Configuration (JavaScript)

const client = new Client({
    apiKey: 'your-langsmith-api-key',
    apiUrl: 'https://your-langsmith-instance.com/api-host'
});

2. Set up OAuth providers

Before agents can authenticate, you need to configure an OAuth provider using the following process:

1. Select a unique identifier for your OAuth provider to use in LangChain’s platform (e.g., “github-local-dev”, “google-workspace-prod”).

2. Go to your OAuth provider’s developer console and create a new OAuth application.

3. Set the callback URL in your OAuth provider:

LangSmith Cloud

https://smith.langchain.com/host-oauth-callback/{provider_id}

For example, if your provider_id is “github-local-dev”, use:

https://smith.langchain.com/host-oauth-callback/github-local-dev

Self-hosted

https://{your-langsmith-instance}/host-oauth-callback/{provider_id}

For example, if your instance is langsmith.example.com and provider_id is “github”, use:

https://langsmith.example.com/host-oauth-callback/github

4. Use client.create_oauth_provider() with the credentials from your OAuth app:

Python

new_provider = await client.create_oauth_provider(
    provider_id="{provider_id}",  # Provide any unique ID
    name="{provider_display_name}",  # Provide any display name
    client_id="{your_client_id}",
    client_secret="{your_client_secret}",
    auth_url="{auth_url_of_your_provider}",
    token_url="{token_url_of_your_provider}",
)

JavaScript

const newProvider = await client.createOAuthProvider({
    providerId: '{provider_id}',  // Provide any unique ID
    name: '{provider_display_name}',  // Provide any display name
    clientId: '{your_client_id}',
    clientSecret: '{your_client_secret}',
    authUrl: '{auth_url_of_your_provider}',
    tokenUrl: '{token_url_of_your_provider}',
});

3. Authenticate from an agent

The client authenticate() API is used to get OAuth tokens from pre-configured providers. On the first call, it takes the caller through an OAuth 2.0 auth flow.

In LangGraph context

By default, tokens are scoped to the calling agent using the Assistant ID parameter.

auth_result = await client.authenticate(
    provider="{provider_id}",
    scopes=["scopeA"],
    user_id="your_user_id"  # Any unique identifier to scope this token to the human caller
)

# Or explicitly specify an agent_id for agent-scoped tokens
auth_result = await client.authenticate(
    provider="{provider_id}",
    scopes=["scopeA"],
    user_id="your_user_id",
    agent_id="specific-agent-id"  # Optional: explicitly set agent scope
)

During execution, if authentication is required, the SDK will throw an interrupt. The agent execution pauses and presents the OAuth URL to the user:

After the user completes OAuth authentication and we receive the callback from the provider, they will see the auth success page.

The agent then resumes execution from the point it left off at, and the token can be used for any API calls. We store and refresh OAuth tokens so that future uses of the service by either the user or agent do not require an OAuth flow.

token = auth_result.token

Outside LangGraph context

Provide the auth_url to the user for out-of-band OAuth flows.

Python

auth_result = await client.authenticate(
    provider="{provider_id}",
    scopes=["scopeA"],
    user_id="your_user_id"
)

if auth_result.status == "pending":
    print(f"Complete OAuth at: {auth_result.url}")
    # Wait for user to complete OAuth
    completed_auth = await client.wait_for_completion(auth_result.auth_id)
    print("Authentication completed!")
else:
    token = auth_result.token
    print(f"Already authenticated, token: {token}")

JavaScript

const authResult = await client.authenticate({
    provider: '{provider_id}',
    scopes: ['scopeA'],
    userId: 'your_user_id'
});

if (authResult.status === 'pending') {
    console.log(`Complete OAuth at: ${authResult.authUrl}`);
    // Wait for user to complete OAuth
    const completedAuth = await client.waitForCompletion(authResult.authId);
    console.log('Authentication completed!');
} else {
    const token = authResult.token;
    console.log(`Already authenticated, token: ${token}`);
}

Troubleshooting

Self-hosted: 405 Method Not Allowed

If you receive a 405 Method Not Allowed error, ensure LANGSMITH_API_URL points to the /api-host path:

export LANGSMITH_API_URL="https://your-instance.com/api-host"

Self-hosted: Malformed OAuth callback URL

Ensure your OAuth provider’s redirect URI matches your LangSmith instance URL:

https://your-instance.com/host-oauth-callback/{provider_id}

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.