Documentation Index
Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
Use this file to discover all available pages before exploring further.
Agent Auth is in
Beta and under active development. To provide feedback or use this feature, reach out to the
LangChain team.
Installation
pip install langchain-auth
npm install @langchain/auth
Quickstart
1. Initialize the client
from langchain_auth import Client
client = Client(api_key="your-langsmith-api-key")
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.
export LANGSMITH_API_URL="https://your-langsmith-instance.com/api-host"
client = Client(api_key="your-langsmith-api-key")
client = Client(
api_key="your-langsmith-api-key",
api_url="https://your-langsmith-instance.com/api-host"
)
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:
-
Select a unique identifier for your OAuth provider to use in LangChain’s platform (e.g., “github-local-dev”, “google-workspace-prod”).
-
Go to your OAuth provider’s developer console and create a new OAuth application.
-
Set the callback URL in your OAuth provider:
LangSmith Cloud
Self-hosted
https://smith.langchain.com/host-oauth-callback/{provider_id}
https://smith.langchain.com/host-oauth-callback/github-local-dev
https://{your-langsmith-instance}/host-oauth-callback/{provider_id}
langsmith.example.com and provider_id is “github”, use:https://langsmith.example.com/host-oauth-callback/github
- Use
client.create_oauth_provider() with the credentials from your OAuth app:
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}",
)
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
)
token = auth_result.token
Outside LangGraph context
Provide the auth_url to the user for out-of-band OAuth flows.
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}")
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"
https://your-instance.com/host-oauth-callback/{provider_id}
