Integrate the SDK

You've registered an Application in AuthSec and copied the introspection secret. The next thing — and the only thing standing between your application and "protected" — is dropping the SDK into your codebase.

It's one import and one function call.

Pick a language​

All three have the same surface area. Each Config field maps 1:1 to a field on the Application detail page — the admin UI emits paste-ready snippets per language in Show Config.

Package names​

Install the package for your language. The repository is named sdk-authsec, but that is not the npm or PyPI package name.

What the wrapper does for you​

When you mount_mcp (or equivalent), every request to your protected path gets:

1. Bearer token extracted from the Authorization header.
2. Token validated — signature, expiry, audience. JWT-local, introspection, or both, depending on validation mode.
3. Tool resolved — the SDK reads the JSON-RPC method or argument to figure out which tool the request is calling.
4. Scope checked against the tool policy you defined.
5. Decision returned — 200 runs the tool, 401/403 returns a structured denial body the AI client can act on.

You write your tools. AuthSec writes the deny rules. The SDK is the bridge.

Config you'll need​

The Application detail page emits a config block. Paste it into your application's environment. Every SDK reads the same keys:

AUTHSEC_RESOURCE_SERVER_ID=525da3b4-4206-4070-ad68-90cc3a6de43b
AUTHSEC_RESOURCE_URI=https://mcp.acme.example/mcp
AUTHSEC_RESOURCE_NAME="Acme MCP"
AUTHSEC_ISSUER=https://auth.authsec.dev
AUTHSEC_AUTHORIZATION_SERVER=https://auth.authsec.dev
AUTHSEC_JWKS_URL=https://auth.authsec.dev/oauth/jwks
AUTHSEC_INTROSPECTION_URL=https://auth.authsec.dev/oauth/introspect
AUTHSEC_INTROSPECTION_CLIENT_ID=525da3b4-4206-4070-ad68-90cc3a6de43b
AUTHSEC_INTROSPECTION_CLIENT_SECRET=...   # only shown once at register time
AUTHSEC_POLICY_MODE=remote_required
AUTHSEC_VALIDATION_MODE=jwt_and_introspect
AUTHSEC_PUBLISH_MANIFEST=true

The SDK reads them via the per-language Config.fromEnv() / from_env() / loadConfigFromEnv().

Older snippets may show AUTHSEC_RESOURCE, AUTHSEC_JWKS_URI, AUTHSEC_INTROSPECTION_ENDPOINT, AUTHSEC_INTROSPECTION_ID, or AUTHSEC_INTROSPECTION_SECRET. The current SDK accepts those aliases for compatibility, but new deployments should use the canonical names above.

Calling a protected server (agent side)​

Protecting a server is half the protocol — the other half is a service or agent that needs a token to call one. The Python SDK covers both directions:

• Machine-to-machine — a pipeline/service acting as itself, with three credential types (client secret, private-key JWT, SPIFFE SVID): M2M auth — three methods
• On behalf of a user — a copilot acting with a signed-in user's permissions via ID-JAG delegation: ID-JAG delegation

Agent frameworks​

LangChain — delegation tokens​

If you're building a LangChain agent that calls downstream APIs on behalf of a user, the authsec-langchain-sdk handles token acquisition and caching automatically.

Open LangChain SDK →

Beyond protecting an MCP server​

The above three are the MCP-server / API / agent protection SDKs — the path most readers will take. AuthSec also ships smaller SDKs for adjacent use cases:

Clients SDK — embed AuthSec in an AI client​

If you're building an AI client (not protecting a server), the Clients SDK wraps the user-facing OAuth flow.

Open Clients SDK →

Workloads SDK — non-human identity​

For autonomous workloads (CI jobs, background agents, scheduled batch processes) that need to authenticate without a human.

Open Workloads SDK →

RBAC SDK — manage roles programmatically​

For provisioning pipelines that sync HR or ticketing data into AuthSec roles and bindings.

Open RBAC SDK →

External Services SDK — secrets and federation​

For pulling credentials AuthSec brokers to a downstream service (Vault, AWS, etc.).

Open External Services SDK →

When something doesn't work​

• SDK FAQ — common questions
• Troubleshoot OAuth tokens — four-claim debug checklist when something's denying that shouldn't

Need help?​

• Getting started guide
• GitHub discussions