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

# FAQ

> Common questions, for evaluators and developers.

## For decision-makers

### What is MudraID, in one sentence?

A trust layer that gives every AI agent a verifiable identity, so the APIs an agent calls can know who's calling, what it's allowed to do, and whether it's still trusted.

### Do we have to run any MudraID infrastructure?

No. MudraID is a managed service. You add a small library on your side — the SDK if you build agents, the middleware if you run an API — and MudraID operates everything else (issuing identities and tokens, publishing keys, processing revocations, keeping the audit log).

### What data does MudraID store?

Agent and platform identities, a one-way hash of each agent secret (never the secret itself), which agents hold which scopes on which platforms, and the audit log of verifications. MudraID does **not** store your secrets in plaintext, and it is not in the path of your business data — it authenticates the call, it doesn't see the request or response payloads. See [Trust & security](/security/overview).

### How long does integration take?

The agent side is a one-line client swap — minutes. The platform side is adding the middleware plus mapping your routes to scopes — typically an afternoon, with scope design being the part worth thinking through. See the [Integration overview](/overview/integration-overview).

### What languages and frameworks are supported?

Today: a Python agent SDK, and middleware for FastAPI and Starlette. More languages and frameworks are planned.

### What happens if MudraID is unavailable?

Platforms verify tokens locally using keys they've already cached, so verification doesn't make a per-request call to MudraID — already-issued tokens keep being accepted. New token minting does go through MudraID, so a sustained outage would eventually prevent agents from getting fresh tokens. Tokens are short-lived by design, so this is a real dependency to weigh, not a hidden one.

### Is there vendor lock-in?

The integration is a thin shim, and the wire format is standard (signed JWTs verified against a published key set). Removing MudraID means removing a library and a config file, not unwinding a deep coupling.

### How is this different from API keys or an API gateway?

A shared API key is long-lived, over-privileged, anonymous, and painful to revoke. MudraID gives each agent its own identity, short-lived scoped tokens, per-agent attribution, and instant revocation — the things a static key can't. See [The problem](/overview/the-problem).

## For developers

### Do I have to rewrite my agent to use MudraID?

No. The SDK is a drop-in replacement for `requests` — swap `requests.get` for `agent.get`. That's it.

### Do I have to add auth code to every route on my platform?

No. The middleware enforces scopes from a YAML file. Your route handlers don't change, and there are no decorators.

### What happens when MudraID rotates its signing key?

Nothing on your end. The middleware sees a token signed by an unknown key, fetches the latest keys, and verifies. No restart, no config change. See [Survive key rotation](/guides/platform-operator/key-rotation).

### My agent's token expired mid-request. What happens?

The SDK handles it. On a `401` from the platform, it refreshes the token and retries once. You don't see it.

### Why isn't `items:write` enough to read items?

Scopes are flat — there's no hierarchy. If a route needs both read and write, the agent must be granted both. It's deliberate, and it removes a class of accidental over-permissioning.

### A route returns 404 but I know it exists. Why?

It either has no rule in `mudraid_scopes.yaml` or is marked `skip: true`. Both return 404, and a hidden route is indistinguishable from a missing one on purpose. Add a rule for the route.

### I changed the scopes file but nothing changed. Why?

The middleware reads the YAML once, at startup. Redeploy or restart to pick up changes — there's no hot-reload. See [Manage the scopes lifecycle](/guides/platform-operator/scopes-lifecycle).

### Can I see my agent's secret again?

No. MudraID stores only a one-way hash. If you've lost the secret, rotate for a new one.

### Is the secret ever written to logs?

No — not in the SDK, the middleware, or MudraID's services. This is enforced by automated tests on every build.

### Where do I report a security issue?

See [Responsible disclosure](/security/disclosure). Please don't open a public issue for a vulnerability.