LangChain SDK — Agent delegation

Before you write any code, two things need to exist in the AuthSec UI: an AI Agent client (gives your agent an identity) and a trust delegation (declares what that agent is allowed to do). Only then does the SDK have something to talk to.

---

Step 1 — Register the AI Agent

1. In the sidebar, go to Clients → MCP Servers / AI Agents.

2. Click Onboard New Client.

3. In the modal, select AI Agent.

4. Enter an AI Agent Name (e.g., Customer Support).

5. Choose the Platform your agent runs on (e.g., Kubernetes).

6. Fill in the platform selectors that identify the workload at runtime:

   Key	Example value
   k8s:ns	production
   k8s:sa	customer-support-sa
   k8s:pod-label:app	customer-support
   k8s:container-name	agent

7. Click + Onboard.

After onboarding, the client detail page shows the Client ID — copy it. You'll set it as AUTHSEC_AGENT_CLIENT_ID in your environment.

---

Step 2 — Create a trust delegation

Trust delegation tells AuthSec which roles and actions the agent may request tokens for.

1. In the sidebar, click Trust Delegation.
2. Click Create trust delegation.
3. Define context:
   • Set the Role the delegation applies to.
   • Set Target Type to Langchain AI agent.
   • Under Client / Application, select the agent you just registered.
4. Assign permissions: choose the Allowed Actions the agent can perform. You can select individual actions or use Select All.
5. Set duration: enter a Maximum Duration and unit (e.g., 1 Hour). Use the shortest window that fits your use case.
6. Click Create Trust Delegation. A successful save returns you to the Trust Delegation dashboard.

---

Step 3 — Install the SDK

pip install authsec-langchain-sdk

The package is on PyPI.

Verify:

python -c "from authsec_langchain import AuthsecClient, AuthsecConfig; print('OK')"

Also install the required dependencies:

pip install "langchain>=1.0,<2.0" "langchain-core>=1.0,<2.0" "PyJWT>=2.8" "cryptography>=41"

---

Step 4 — Configure the client

import os
from authsec_langchain import AuthsecClient, AuthsecConfig

authsec = AuthsecClient(AuthsecConfig(
    base_url=os.environ["AUTHSEC_BASE_URL"],
    client_id=os.environ["AUTHSEC_AGENT_CLIENT_ID"],  # from Step 1
))

The client caches the delegation token internally and only hits the network on first call or after expiry.

---

Step 5 — Define a tool with delegation

Call authsec.get_delegation_token() at the start of any tool that needs to act on behalf of the user. Pass the returned JWT as a Bearer token to your downstream API.

from langchain_core.tools import tool
import httpx

DOWNSTREAM_URL = os.environ["DOWNSTREAM_URL"]

@tool
def get_customer_billing(customer_id: str) -> dict:
    """Get billing details for a customer by their ID."""
    jwt_token = authsec.get_delegation_token()
    resp = httpx.get(
        f"{DOWNSTREAM_URL}/billing/customers/{customer_id}",
        headers={"Authorization": f"Bearer {jwt_token}"},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

---

Step 6 — Run the smoke test

export AUTHSEC_BASE_URL="https://your-authsec-server"
export AUTHSEC_AGENT_CLIENT_ID="your-client-id"
python examples/smoke_local.py

On Windows (PowerShell):

$env:AUTHSEC_BASE_URL = "https://your-authsec-server"
$env:AUTHSEC_AGENT_CLIENT_ID = "your-client-id"
python examples/smoke_local.py

---

How the delegation token endpoint works

The SDK calls one endpoint under the hood:

Method	Path
GET	/authsec/uflow/sdk/delegation-token?client_id=<id>

Response:

{ "token": "<RS256 JWT>", "expires_at": "2026-05-21T07:25:36Z" }

Set base_url to your AuthSec server root — the SDK appends /authsec/... automatically.