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

# The trust model

> The mental model behind MudraID: who's calling, what they can do, and whether to trust them.

Everything in MudraID follows from one idea: every call an agent makes should answer three questions before it's served. Once you hold that idea, the rest of the system is just the machinery that answers them reliably.

## The three questions

An API call from an agent arrives as ordinary HTTP. On its own, it tells the receiver nothing it can trust. MudraID makes every call answer:

* **Who is this agent?** A cryptographic identity that can't be faked — not an IP address, a header, or a guess.
* **What is it allowed to do here?** A specific permission (a *scope*), decided by the platform being called.
* **Is it still trusted right now?** A live status. An agent trusted a minute ago can be revoked, and the next call reflects that.

A shared API key answers none of these well. MudraID answers all three on every request.

## The three roles

Three parties cooperate. You're usually only one of them.

| Role         | What it uses        | Its job                                                                                         |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------- |
| **Agent**    | The Python SDK      | Prove who it is on every call it makes                                                          |
| **Platform** | The middleware      | Verify the agent and its scope before serving a request                                         |
| **MudraID**  | The managed service | Issue identities and tokens, publish verification keys, process revocations, keep the audit log |

You add a small library on your side. MudraID runs the part in the middle.

## How trust flows

1. **An agent is registered once** and receives its credentials: a public id and a secret.
2. **The SDK trades the secret for a short-lived token.** This happens automatically, behind your `agent.get(...)` call.
3. **MudraID signs the token** with a private key only it holds.
4. **The platform verifies the token** against MudraID's public keys — on its own, without calling MudraID per request.
5. **The platform checks the scope** the route requires against the scopes in the token.
6. **MudraID records the verification**, pass or fail.

## The key insight: secret in, token out

The agent's long-lived secret never leaves for the platforms it calls. The SDK exchanges it for a token, and only the token travels onward. The platform only ever sees something it can verify by itself.

That separation is what makes the model safe:

* A platform can't leak your secret, because it never had it.
* A token is useless after a few minutes.
* Verification needs no shared secret between you and the platform — just MudraID's public keys.

## Why tokens are short-lived

Short-lived tokens shrink the blast radius of anything going wrong. If a token is captured, it stops working within minutes. If the agent itself is compromised, you revoke it and no new tokens are issued. You never have to rotate a long-lived shared secret across every caller at once.

## A worked example

A travel agent calls an airline's booking API.

1. The agent has been granted `flights:search` and `flights:book` on that airline.
2. It calls `GET /flights`. The SDK fetches a token carrying those scopes and attaches it.
3. The airline's middleware verifies the token and sees `flights:search` is present — the request is served.
4. Later the agent calls `POST /bookings`, which requires `flights:book`. The token carries it, so that's served too.
5. If the airline revokes the agent, the very next call fails — no code change on either side.

## Where to go next

* [Agent identity](/guides/concepts/agent-identity) — the credentials behind "who is this agent."
* [Authentication and tokens](/guides/concepts/auth-tokens) — how tokens are minted and verified.
* [Platforms and scopes](/guides/concepts/platforms-scopes) — how "what it can do" is decided.