Skip to main content
An agent’s credential never travels to the platforms it calls. The agent’s linked OAuth machine client authenticates to MudraID’s token endpoint, receives a short-lived access token for one approved resource, and only that 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 signs the client assertion, 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 resource, the SDK calls POST /oauth2/token with the client_credentials grant, the exact approved resource, and the scopes it needs. MudraID returns a signed access token (an RFC 9068 at+jwt) that:
  • is signed by MudraID with a private key only it holds,
  • expires in five minutes by default,
  • is audience-bound to the one resource it was requested for, and
  • carries exactly the scopes requested — each must be covered by the client’s approved grant for that resource, or the request is refused.
The SDK keeps the token in memory and reuses it for later calls, refreshing it shortly before it expires. Machine clients never receive a refresh token; the SDK simply authenticates again.

​
Token lifetime

The access-token lifetime is 300 seconds (five minutes) by default. Operators can tune it, but never above a 900-second (fifteen-minute) ceiling — a value above the ceiling is clamped down to it, so no token is ever minted with a longer life than that. Don’t hardcode either number. The token response returns the lifetime actually applied in expires_in, and that is the value to trust; the SDK already schedules its refresh from it.

​
What happens when permissions change

Revoking the grant, suspending the client or retiring its key prevents new access tokens from being issued. A token already issued may remain usable by a surface validating it offline until it expires—five minutes by default and never longer than the configured fifteen-minute ceiling. Integrations using live enforcement consult current authority and containment on each protected action.

​
Client authentication methods

Your machine client authenticates at POST /oauth2/token in one of two ways. Present exactly one. The private key never leaves your environment — you register only its public JWK and prove possession of it. A private_key_jwt client cannot fall back to a shared secret; an attempt to downgrade is refused. A secret sent in the form body is not a supported method.
Native agent credentials are retired. The old api_key_id + secret pair and POST /api/v1/auth/token now return 410 Gone. Register an agent identity, link a machine client to it, and use /oauth2/token. See Versioning and deprecation.
private_key_jwt authenticates the client at the token endpoint. It does not make the resulting access token theft-proof — the access token is still a bearer token, usable by whoever holds it until it expires or its authority is revoked. Binding a token to its sender requires a sender-constrained profile (DPoP or mTLS); neither is implemented today. Keep treating access tokens as secrets.

​
Verifying a token

This section describes offline verification: the middleware verifies the token locally, and MudraID is not called while the request is being served. (The other mode, live enforcement, asks MudraID’s /decide on each protected action with the same access token — see the trust model.) When the request reaches the platform, the middleware checks: Only if every check passes does the middleware then look at scope. Configure the accepted issuer and audience explicitly — see middleware configuration. During an issuer migration, operators can accept a set of issuers.

​
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 /.well-known/jwks.json. 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 resource

The audience (aud) claim ties a token to a single resource. A token minted for resource A is rejected by resource 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 requests a separate token for each, scoped and audience-bound to that resource. The bank’s middleware will not accept a token meant for the airline.

​
What you actually do

As an agent developer: configure the linked client and approved resource, then make calls — the SDK handles tokens. As a platform operator: add the middleware, define scopes, and set the accepted issuer and audience; verification is automatic. The mechanics above run for you.