An agent’s identity is the foundation of everything else. Before it can get tokens or call anything, an agent is registered with MudraID and given two credentials.
The two credentials
| Credential | Prefix | Public? | Use |
|---|
api_key_id | muid_kid_ | Public | Identifies the agent. Safe to log and share. |
secret | muid_sk_ | Private | Proves the agent is who it claims. Never log or share it. |
api_key_id as a username and the secret as a password — except the secret is exchanged for short-lived tokens rather than sent to the services your agent calls.
MUDRAID_API_KEY_ID=muid_kid_a3f8e9c1d2b4f5e6a7b8c9d0e1f2a3b4
MUDRAID_SECRET=muid_sk_xY9kL2pQ4rT6vN8mZ1cX3bV5nL7kJ9hG
Registration
When an agent is registered, MudraID:
- Generates the
api_key_id.
- Generates the
secret.
- Stores only a one-way hash of the secret.
- Returns the plaintext secret to you once.
After that moment, the plaintext secret exists nowhere on MudraID’s side — only its hash. MudraID cannot show it to you again, even to its own operators. If you lose it, you rotate for a new one.
Capture the secret when it’s shown. It’s displayed exactly once and can’t be recovered.
Why you can’t retrieve the secret later
This is deliberate, and it’s what protects you if MudraID’s database is ever stolen.
MudraID stores a one-way hash of your secret — with a server-side secret value (a “pepper”) mixed in — never the secret itself. A hash can’t be reversed back into the secret. So even a full copy of the database doesn’t yield a usable credential — there’s nothing in it to replay.
Verification is also constant-time: checking a secret takes the same amount of time whether it’s almost right or completely wrong, so an attacker can’t measure timing to recover it piece by piece.
Storing your credentials
- Keep both values in environment variables or a secrets manager — never in source code.
- Add
.env to .gitignore.
- The
api_key_id is safe to log; the secret must never be logged.
- Grant each agent only the scopes it needs. A narrowly scoped agent is a smaller problem if it’s ever compromised.
Rotating the secret
If a secret is exposed, rotate it. MudraID issues a new secret and keeps the old one valid for a short grace window, so requests already in flight don’t break during the swap. Update your environment with the new value and you’re done.
See Rotate a compromised secret for the steps.
A note on history
Earlier versions of MudraID used public-key cryptography with a challenge-response handshake for agent identity. v1 moved to the API key plus token model described here — simpler to integrate and a drop-in HTTP experience. The older verification endpoints are retired. 
