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

# Authentication and tokens

> How an agent's secret becomes a short-lived token, and how platforms verify it.

An agent's secret never travels to the platforms it calls. Instead, the SDK exchanges the secret for a short-lived token, and only the token is sent onward. This page explains how that token is created, what it carries, and how a platform checks it.

The good news for developers: **you don't manage any of this directly.** The SDK mints, caches, and refreshes tokens; the middleware verifies them. This page is the model behind that automation, for when you need to reason about it.

## Minting a token

When your agent makes its first call to a platform, the SDK requests a token from MudraID, presenting the agent's credentials. MudraID returns a signed token (a JWT) that:

* is **signed by MudraID** with a private key only it holds,
* **expires in about 15 minutes**, and
* **carries the scopes** the agent holds **for that one platform**.

The SDK keeps the token in memory and reuses it for later calls, refreshing it shortly before it expires. Your code never waits on this — it's invisible.

## Verifying a token

When the request reaches the platform, the middleware verifies the token by itself — no callback to MudraID on each request. It checks:

| Check                              | What it confirms                                                                       |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| **Signature**                      | The token was issued by MudraID and hasn't been tampered with.                         |
| **Issuer (`iss`)**                 | It was issued by MudraID (the default issuer is `mudraid-identity`), not someone else. |
| **Audience (`aud`)**               | It was minted for *this* platform specifically.                                        |
| **Timing (`exp` / `nbf` / `iat`)** | It's within its valid window — not expired, not used early.                            |

Only if every check passes does the middleware then look at scope.

By default the middleware accepts the single issuer `mudraid-identity`. During an issuer migration, operators can configure it to accept a set of issuers — see [middleware configuration](/sdks/middleware/configuration).

## Why the algorithm is pinned

The middleware only accepts tokens signed with MudraID's asymmetric algorithm (RS256). It rejects anything else — including classic JWT attacks that try to downgrade the algorithm or pass an unsigned token. This check happens before any signature work, so a malformed or hostile token is thrown out immediately.

## Verification keys (JWKS)

To verify signatures, the middleware needs MudraID's public keys. MudraID publishes them at a well-known URL (a JWKS endpoint). The middleware fetches them once and caches them, so steady-state verification is local and fast.

Public keys verify; they can't sign. Publishing them is safe — only MudraID can mint tokens, but anyone can check them.

## Key rotation is automatic

MudraID rotates its signing keys periodically. When a token arrives signed by a key the middleware hasn't seen, the middleware fetches the latest keys, finds the new one, and verifies — with no downtime and no action from you. See [Survive key rotation](/guides/platform-operator/key-rotation).

## Tokens are bound to one platform

The audience (`aud`) claim ties a token to a single platform. A token minted for platform A is rejected by platform B, even though both trust MudraID. So a token captured on its way to one platform can't be replayed against another.

**Example.** Your agent calls both an airline and a bank. The SDK mints a separate token for each, scoped and audience-bound to that platform. The bank's middleware will not accept a token meant for the airline.

## What you actually do

As an agent developer: nothing — make calls, the SDK handles tokens. As a platform operator: add the middleware and define scopes; verification is automatic. The mechanics above run for you.