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

# Register and manage an agent

> Create an agent, grant it least-privilege access, and manage it over time.

An agent has to exist in MudraID before your code can make authenticated calls. This guide covers creating one, granting it the right access, and managing it through its life.

## Register

You can register through the portal or the API. Either way, three things happen:

1. **Create the agent.** It gets an identity.
2. **Grant it platforms.** Which services is it allowed to call?
3. **Grant it scopes.** On each platform, what specifically may it do?

You then receive its two credentials, once:

* `MUDRAID_API_KEY_ID` — public identifier.
* `MUDRAID_SECRET` — private credential.

<Warning>
  The secret is shown exactly once and can't be retrieved later — MudraID keeps only a one-way hash. Capture it at creation time.
</Warning>

## Store the credentials

Put them in environment variables or a secrets manager — never in source code.

```env theme={null}
MUDRAID_API_KEY_ID=muid_kid_...
MUDRAID_SECRET=muid_sk_...
```

Add `.env` to `.gitignore`. The `api_key_id` is safe to log; the `secret` must never be.

## Grant only what's needed

Give each agent the smallest set of scopes that does its job. This is the single most effective thing you can do to limit damage if an agent is ever compromised.

A few rules of thumb:

* If the agent only reads, grant only read scopes.
* Remember scopes are **flat** — `items:write` does not include `items:read`. If the agent needs to do both, grant both explicitly.
* Prefer several narrowly-scoped agents over one agent that can do everything.

**Example.** A reporting agent that only summarizes orders should hold `orders:read` — nothing else. Even if its secret leaks, it can't create or cancel anything.

## Manage the agent over time

* **Rotate the secret** if it's exposed, or on a routine schedule. The old secret stays valid for a short grace window so in-flight calls don't break. See [Rotate a compromised secret](/guides/agent-developer/rotate-secret).
* **Revoke the agent** when it should stop working entirely. It immediately stops getting new tokens; any token already issued expires within minutes.
* **Re-grant scopes** when the agent's job changes. Update its grants in the portal — scope changes on platforms the agent already uses take effect on its next token, no redeploy. Granting access to a **new platform** is the exception: the SDK caches its platform list at startup, so the agent must call `Agent.refresh_platforms()` or restart to pick it up.

## Related

* [Quickstart: Agent Developer](/guides/get-started/quickstart-agent)
* [Agent identity](/guides/concepts/agent-identity)
* [Configuration](/sdks/python-sdk/configuration)