MudraID — a trust layer for AI agents

Configure the SDK with MachineAgent.from_env() to use a linked OAuth client. Select the authentication method configured for that client.

Settings

Set process environment variables before starting your application. The SDK does not load .env files automatically. Use values for the intended organization, environment and approved resource; there is no implicit production endpoint.

Setting	Env var	Default
Authentication method	`MUDRAID_AUTH_METHOD`	`private_key_jwt`
Client secret (secret method only)	`MUDRAID_CLIENT_SECRET`	(required)
Linked OAuth client	`MUDRAID_CLIENT_ID`	(required)
OAuth token endpoint	`MUDRAID_TOKEN_ENDPOINT`	(required)
Assertion audience	`MUDRAID_ASSERTION_AUDIENCE`	(required)
Approved resource	`MUDRAID_RESOURCE`	(required)
Requested scopes	`MUDRAID_SCOPES`	Empty scope set
Private key file	`MUDRAID_PRIVATE_KEY_PATH`	(required)
Registered key ID	`MUDRAID_KEY_ID`	(required)

Choose private_key_jwt for a signing key or client_secret_basic for a client secret. Both use an approved resource/scopes grant. Client-secret use remains subject to the server’s policy and approval requirements. The secret method does not read an assertion audience or key file. The key file and key ID are required for the built-in signer. Passing a custom signer= avoids reading these two variables or opening a local key file.

from mudraid import MachineAgent

agent = MachineAgent.from_env("WEBSITE_API")

A custom prefix reads only that prefix’s variables, such as WEBSITE_API_CLIENT_ID. Missing values raise MudraIDConfigError; the loader never switches to another identity or falls back to native key/secret credentials. For direct configuration, pass a MachineIdentity to MachineAgent. The token endpoint requires HTTPS, except literal loopback hosts for local tests. Userinfo, fragments, whitespace and invalid ports are rejected before signing or network traffic. Use the exact assertion audience and resource accepted by your server. Keep private key files out of version control and logs. Give each resource/scoped configuration its own SDK instance. Set request timeouts explicitly and call close() when finished. Caller-supplied sessions and token managers remain the caller’s responsibility. See Quickstart.

Multiple clients in one application

Choose a different environment-variable prefix for each configuration. The prefix is your application’s label, not the agent name or OAuth client display name. Two clients linked to the same agent can use separate prefixes. Registering a client in the portal does not change your process environment. Load both sets into the process using your deployment configuration or an explicit .env loader. Replace all placeholders; never commit private keys or secrets.

TASKS_CLIENT_ID=<tasks client ID>
TASKS_TOKEN_ENDPOINT=<HTTPS token endpoint for the selected environment>
TASKS_ASSERTION_AUDIENCE=<exact server assertion audience>
TASKS_RESOURCE=<approved tasks resource URI>
TASKS_SCOPES=tasks:read
TASKS_PRIVATE_KEY_PATH=<local tasks private key file>
TASKS_KEY_ID=<registered tasks key ID>

PAYMENTS_CLIENT_ID=<payments client ID>
PAYMENTS_TOKEN_ENDPOINT=<HTTPS token endpoint for the selected environment>
PAYMENTS_ASSERTION_AUDIENCE=<exact server assertion audience>
PAYMENTS_RESOURCE=<approved payments resource URI>
PAYMENTS_SCOPES=payments:execute
PAYMENTS_PRIVATE_KEY_PATH=<local payments private key file>
PAYMENTS_KEY_ID=<registered payments key ID>

Create separate SDK instances using the matching prefixes:

from mudraid import MachineAgent

tasks = MachineAgent.from_env("TASKS")
try:
    payments = MachineAgent.from_env("PAYMENTS")
    try:
        # Use tasks for the approved tasks resource and payments for payments.
        # Pass an explicit timeout on each request.
        pass
    finally:
        payments.close()
finally:
    tasks.close()

TASKS reads only TASKS_*; PAYMENTS reads only PAYMENTS_*. Missing required settings raise MudraIDConfigError. The SDK does not use another prefix to repair missing configuration. Reusing one prefix for two configurations replaces values in your own process environment, so keep the prefixes distinct. A client can have multiple approved grants. Each SDK instance selects one resource and requested scope set; using separate instances does not require registering a new OAuth client for every grant. Dedicated clients and keys are an option when you need stronger separation between workloads. Configuration never grants access. Separate prefixes and SDK objects do not isolate private keys from code running in the same process. Where your threat model requires isolation, also restrict which workload can access each key or signing service. Never retry a refused request automatically with a more privileged client.

Endpoint, assertion audience and resource are different settings

Use the token endpoint and assertion audience supplied for the selected deployment; do not assume a universal production or staging default. The assertion audience identifies the authorization server for client authentication. The resource URI identifies the protected API and is the access-token audience the API must accept. Neither is the local environment-variable prefix. For ordinary HTTP route-scope middleware, keep the actual platform UUID in mudraid_scopes.yaml. Configure expected_issuer with the trusted authorization server issuer and expected_audience with the exact approved resource URI. Do not replace the platform UUID with the resource URI, disable issuer/audience checks, or infer trusted values from an unverified token. An issuer or audience refusal means you should check these settings against the selected environment and grant. Published mudraid-platform-middleware 1.4.0 already supports both settings for ordinary HTTP route-scope enforcement. Configure the protected API separately from the calling agent:

from mudraid_platform_middleware import MudraIDMiddleware

app.add_middleware(
    MudraIDMiddleware,
    scopes_yaml_path="./mudraid_scopes.yaml",  # retain the real platform UUID
    jwks_url="<trusted JWKS URL for this environment>",
    expected_issuer="<trusted authorization-server issuer>",
    expected_audience="<exact approved resource URI>",
)

Read the issuer and JWKS URL from the authorization-server metadata at your trusted deployment, and the resource from the approved grant. Replace the placeholders before running the API. The issuer is not the token endpoint or the client’s assertion audience. WRONG_ISSUER means the API’s configured issuer does not match the issuing server; WRONG_AUDIENCE means its accepted resource does not match the token’s audience. Check the selected environment and approved grant rather than adding every observed issuer or audience to an allowlist.

Trusted destinations

By default, the client sends access tokens only to the origin of the configured resource URI. A different host, port or scheme is refused before token issuance. For a non-HTTP resource identifier or a separate trusted endpoint, set the matching prefix’s RESOURCE_ORIGINS to a space-separated list of explicit origins such as https://api.example. Origins have no path or query; they do not broaden the resource or scopes granted by MudraID. An empty list fails closed. Automatic redirects are disabled. A redirect response is returned to your app; make a new request only after deciding that its destination is appropriate. The SDK applies the same origin check to that new request. Remote destinations must use HTTPS; explicit loopback HTTP is supported for local development.

Explicit client manager (SDK 2.1.0 and later)

AgentManager is available in the published mudraid-sdk 2.1.0 release. Install it with pip install "mudraid-sdk==2.1.0". Existing applications can continue using the separate MachineAgent.from_env instances above. The manager simplifies initialization and cleanup without guessing credentials:

from mudraid import AgentManager

with AgentManager.from_env({"tasks": "TASKS", "payments": "PAYMENTS"}) as agents:
    tasks = agents.client("tasks")
    payments = agents.client("payments")
    # Bind these clients to the appropriate application tool wrappers once.

Only listed prefixes are loaded. Missing settings fail locally; multiple profiles require a name. Unknown names and denied requests never switch credentials. Instances and token caches are reused independently, including when clients share a resource. A manager constructed from existing clients borrows them; the caller closes those clients. Environment-created clients are manager-owned. The manager is synchronous and adds no thread-safety guarantee to its clients. It does not route requests, select permissions for an AI model or isolate keys from other code in the same process. Closing pools is not credential revocation.

Recovering from setup failures

Symptom	Next action
Missing prefixed setting	Set the named variable for that profile; check explicit environment loading.
Unknown or ambiguous profile	Bind the tool to a configured profile by name.
Token authentication refused	Check client status, key registration, key ID and exact assertion audience.
Destination refused locally	Check the approved resource and deliberate trusted-origin configuration. Do not disable destination checks.
Permission denied	Check the selected client’s effective grant and requested scopes in the correct organization/environment.
Authorization decision expired	Obtain fresh authorization for a new attempt. An expired allow cannot be used; do not replay an uncertain consequential operation automatically.
Credentials revoked	Restore or replace credentials through the authorized administration flow, not by selecting a stronger client.

Start validation with a harmless permitted operation and an intentionally denied operation. Token acquisition alone does not prove that every action is authorized. Inspect the HTTP response and correlated evidence before treating an operation as executed. Do not log credentials or bearer tokens while troubleshooting.

Get Started

Concepts

Agent Developer

Platform Operator

Python Agent SDK

FastAPI Middleware

Configuration

Settings

Multiple clients in one application

Endpoint, assertion audience and resource are different settings

Trusted destinations

Explicit client manager (SDK 2.1.0 and later)

Recovering from setup failures

​Settings

​Multiple clients in one application

​Endpoint, assertion audience and resource are different settings

​Trusted destinations

​Explicit client manager (SDK 2.1.0 and later)

​Recovering from setup failures

Settings

Multiple clients in one application

Endpoint, assertion audience and resource are different settings

Trusted destinations

Explicit client manager (SDK 2.1.0 and later)

Recovering from setup failures