MudraID Python SDK

Authenticate AI agents through a linked OAuth machine client and call its approved resource.

Configure a linked machine client

Register an OAuth machine client, bind it to the intended agent, register its public JWK, complete proof of possession, and approve the exact resource/scopes in the correct organization and environment. Linking alone grants no authority. The same workflow works in sandbox and production, subject to server eligibility checks.

Install the SDK and signing dependencies:

pip install mudraid-sdk 'PyJWT>=2.13,<3' 'cryptography>=50'

Set these process environment variables, using your environment's actual values:

from mudraid import Agent

agent = Agent.from_env()  # reads explicit process environment variables
try:
    response = agent.get("https://your-platform.example/tasks", timeout=15)
    response.raise_for_status()
finally:
    agent.close()

Agent.from_env("WEBSITE_API") uses only WEBSITE_API_* values. Missing configuration fails locally; it never switches to another client's variables. For custom/KMS signing, pass signer=my_signer; no local key file is then read. For explicit configuration use Agent(MachineIdentity(...)). MachineAgent remains available as an alias for the same client implementation.

The token endpoint requires HTTPS; HTTP is accepted only for explicit loopback hosts in local development. Userinfo, fragments, whitespace and invalid ports are rejected before signing or network traffic. Assertions are not followed through redirects. Private keys stay local.

Several clients in one application

The development source adds an optional AgentManager; check the published release notes before using it with a registry installation. Existing MachineAgent.from_env(prefix) instances remain supported.

Configure each workload using a distinct prefix, then initialize once:

from mudraid import AgentManager

with AgentManager.from_env({"tasks": "TASKS", "payments": "PAYMENTS"}) as agents:
    tasks = agents.client("tasks")
    payments = agents.client("payments")
    # Inject these reusable clients into the corresponding tool wrappers.
    # Make requests only to each client's explicitly configured destinations.

The manager reads only the named prefixes and never loads .env files or discovers other credentials. Each profile must have complete settings. There is no fallback after a missing setting, denied request or unknown profile. client() without a name is accepted only for a single-profile manager.

One client can use multiple approved scopes; separate clients are useful for workload ownership, independent revocation and permission boundaries, not a requirement for every endpoint. Two clients can share a resource. Bind the profile in trusted application code, not a model-generated account choice. Server-side authorization remains required for every protected operation.

AgentManager({"tasks": existing_agent}) borrows that client; the caller closes it. from_env creates clients that the manager closes. Closing the manager prevents further selection, but cannot invalidate client references already held by application code. Do not use close() as credential revocation. The manager does not add thread-safety or async guarantees, URL routing, privileged retries, process isolation or private-key isolation.

Client-secret authentication settings

Set MUDRAID_AUTH_METHOD=client_secret_basic and MUDRAID_CLIENT_SECRET, along with the client ID, token endpoint, resource and requested scopes. Use the same Agent.from_env() entry point. This method requires no signing key or assertion audience. The server's policy/approval requirements still apply.

For explicit configuration, pass ClientSecretIdentity(client_id=..., token_endpoint=..., resource=..., client_secret=...) to Agent. A credential failure never switches methods or selects a different environment automatically.

Requests, retries and failures

get, head, options, post, put, patch and delete return requests responses. Tokens are cached per identity and refreshed near expiry. Give each resource/scoped identity its own client. Set request timeouts explicitly.

A consequential POST/PATCH without an idempotency key is not blindly retried after an ambiguous transport failure or a resource-server 401. Ambiguous transport failures raise MudraIDExecutionUnknownError; an unreplayed 401 is returned. An idempotent method or server-deduplicated idempotency_key permits one consequence-safe recovery. Passing a key requires the server to actually deduplicate it; the SDK cannot provide that guarantee by itself.

Catch MudraIDError for SDK errors. MudraIDConfigError identifies local setup failures, MudraIDAuthError authentication refusals, MudraIDRevokedError authority refusals, MudraIDRateLimitedError rate limits (with optional retry_after_seconds), and MudraIDBillingFrozenError billing/plan refusals. close() releases connections owned by the client; explicitly supplied token managers/sessions remain caller-owned.

See the runnable linked-client example. Publication does not itself establish a live platform integration or production readiness; qualify the configured grant and protected resource end to end.