Authentication and tokens

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

​

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.

​

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.