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

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

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.
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:
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

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.