Skip to main content
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

Think of the 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.

​
Registration

When an agent is registered, MudraID:
  1. Generates the api_key_id.
  2. Generates the secret.
  3. Stores only a one-way hash of the secret.
  4. 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.