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

# Agent identity

> How an agent proves who it is: its credentials, how the secret is stored, and how to rotate it.

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

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.

```env theme={null}
MUDRAID_API_KEY_ID=muid_kid_a3f8e9c1d2b4f5e6a7b8c9d0e1f2a3b4
MUDRAID_SECRET=muid_sk_xY9kL2pQ4rT6vN8mZ1cX3bV5nL7kJ9hG
```

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

<Warning>
  Capture the secret when it's shown. It's displayed exactly once and can't be recovered.
</Warning>

## 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](/guides/agent-developer/rotate-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.