> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudraid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Agent Developer

> Give your agent a verifiable identity and make its calls authenticated.

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.

<Warning>
  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.
</Warning>

## 2. Add the credentials to `.env`

```env theme={null}
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

```bash theme={null}
pip install mudraid-sdk
```

<Note>
  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.
</Note>

## 4. Swap `requests` for `Agent`

The SDK is a drop-in replacement for `requests`. Change the client, keep everything else.

```python theme={null}
# 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:

```python theme={null}
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 see                        | What it means                                                      | Fix                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `MudraIDConfigError`                | Credentials missing or blank                                       | Check `MUDRAID_API_KEY_ID` and `MUDRAID_SECRET` are set in `.env` or the environment |
| `MudraIDAuthError`                  | MudraID rejected the credentials                                   | The key id / secret pair is wrong — rotate or re-check                               |
| `MudraIDRevokedError`               | The agent is inactive, or lacks platform/scope access              | Check the agent's status and grants in the portal                                    |
| `MudraIDPlatformNotRegisteredError` | The host you called isn't a platform this agent is registered with | Register the agent for that platform, or check the URL                               |

See [Handle errors](/guides/agent-developer/error-handling) for the full picture.

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" href="/sdks/python-sdk/configuration">
    Settings, precedence, and environments.
  </Card>

  <Card title="Handle errors" href="/guides/agent-developer/error-handling">
    The exception hierarchy and how to use it.
  </Card>

  <Card title="Register & manage an agent" href="/guides/agent-developer/register-agent">
    Scopes, rotation, and revocation.
  </Card>

  <Card title="How it works" href="/overview/how-it-works">
    The model behind the trust loop.
  </Card>
</CardGroup>