Skip to main content
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.
The secret is shown exactly once and can’t be retrieved later — MudraID keeps only a one-way hash. Capture it at creation time.

​
Store the credentials

Put them in environment variables or a secrets manager — never in source code. 
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.
  • 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.