Skip to main content
This guide takes you from nothing to an agent whose API calls are authenticated by MudraID. The integration itself is a one-line change — most of this page is explaining what’s happening so you can reason about it later. By the end you’ll have an agent that fetches and refreshes its own tokens automatically, with no auth code of your own.

​
Before you start

  • A MudraID account, with an agent registered (step 1 below).
  • Python 3.10 or newer.
  • An existing piece of code that makes HTTP calls with requests — or a willingness to write three lines.

​
1. Register an agent

Sign in to the MudraID portal, create an agent, and grant it the platforms and scopes it needs. (You can also do this through the API.) You’ll receive two values, once:
  • MUDRAID_API_KEY_ID — the agent’s public identifier. Safe to log.
  • MUDRAID_SECRET — the private credential. Treat it like a password; never log it.
The secret is shown a single time. Copy it now. MudraID stores only a one-way hash, so it genuinely cannot show it to you again — if you lose it, you rotate for a new one.

​
2. Add the credentials to .env

MUDRAID_API_KEY_ID=muid_kid_a3f8e9c1d2b4f5e6a7b8c9d0e1f2a3b4
MUDRAID_SECRET=muid_sk_xY9kL2pQ4rT6vN8mZ1cX3bV5nL7kJ9hG
Add .env to your .gitignore so the secret never lands in version control. The SDK loads this file on its own — you don’t have to read it yourself.

​
3. Install the SDK

pip install mudraid-sdk
During the v0.1 alpha the package isn’t on PyPI yet. Install from source: pip install -e sdks/mudraid-sdk-python from the repo root.

​
4. Swap requests for Agent

The SDK is a drop-in replacement for requests. Change the client, keep everything else. 
# Before
import requests
response = requests.get("https://api.skyscanner.com/flights")

# After
from mudraid import Agent
agent = Agent()  # reads MUDRAID_* from .env
response = agent.get("https://api.skyscanner.com/flights")
Agent mirrors the requests interface — get, post, put, delete, and the usual keyword arguments (params, json, headers, timeout, …) all work, and you get back a normal requests.Response.

​
Verify it works

Make a call to a platform your agent is registered with and check the status: 
from mudraid import Agent

agent = Agent()
r = agent.get("https://api.skyscanner.com/flights")
print(r.status_code)   # 200 if the agent is allowed
A 200 (or the platform’s normal response) means the trust loop ran end to end: your agent authenticated, the platform verified it, and the call went through.

​
What just happened

On that first call the SDK did four things, all invisibly:
  1. Resolved the URL’s host to the right MudraID platform.
  2. Minted a short-lived token for that platform, using your credentials.
  3. Attached it as an Authorization: Bearer header.
  4. Forwarded the request and returned the response unchanged.
The token is cached in memory and refreshed shortly before it expires. If a platform ever returns 401 mid-flight, the SDK refreshes once and retries — so token expiry never surfaces in your code.

​
Troubleshooting

What you seeWhat it meansFix
MudraIDConfigErrorCredentials missing or blankCheck MUDRAID_API_KEY_ID and MUDRAID_SECRET are set in .env or the environment
MudraIDAuthErrorMudraID rejected the credentialsThe key id / secret pair is wrong — rotate or re-check
MudraIDRevokedErrorThe agent is inactive, or lacks platform/scope accessCheck the agent’s status and grants in the portal
MudraIDPlatformNotRegisteredErrorThe host you called isn’t a platform this agent is registered withRegister the agent for that platform, or check the URL
See Handle errors for the full picture.

​
Next steps

Configuration

Settings, precedence, and environments.

Handle errors

The exception hierarchy and how to use it.

Register & manage an agent

Scopes, rotation, and revocation.

How it works

The model behind the trust loop.