Skip to main content
Everything in MudraID follows from one idea: every call an agent makes should answer three questions before it’s served. Once you hold that idea, the rest of the system is just the machinery that answers them reliably.

​
The three questions

An API call from an agent arrives as ordinary HTTP. On its own, it tells the receiver nothing it can trust. MudraID gives every call an answer to:
  • Who is this agent? A cryptographic identity that can’t be faked — not an IP address, a header, or a guess.
  • What is it allowed to do here? A specific permission (a scope), decided by the platform being called.
  • Is it still trusted? Trust is re-established every time a token is minted, and — for integrations using live enforcement — re-checked on each protected action.
Live enforcement adds a fourth, sharper question: should this exact action be allowed right now? That one is answered by MudraID’s /decide, per protected action. A shared API key answers none of these well. How promptly the trust question is re-answered depends on which enforcement mode you run, so it’s worth knowing the difference before you read further.

​
Two enforcement modes

MudraID integrations run in one of two modes. They differ in one respect that matters: whether MudraID is consulted while a request is being served. Offline verification is the simpler integration and is what the quickstarts set up. Live enforcement is what you add when a decision must reflect the present state of the world rather than the state at the moment the token was minted. Both modes use the same access token, so an agent does not change when a platform moves to live enforcement. The platform does: it registers an enforcement adapter, publishes a signed action bundle, and wires the adapter in front of its protected actions. /decide is deny-closed — anything it cannot decide safely is refused, never allowed. See How it works for the full Authority → Decision → Containment → Proof loop.

​
The three roles

Three parties cooperate. You’re usually only one of them. You add a small library on your side. MudraID runs the part in the middle.

​
How trust flows

Taking offline verification, the mode the quickstarts set up:
  1. An agent identity is registered once, and an OAuth machine client is linked to it. The client registers a public key; the private key stays with you. A resource grant approves exactly which resource and scopes it may use.
  2. The SDK trades a signed client assertion for a short-lived access token. This happens automatically, behind your agent.get(...) call.
  3. MudraID checks the client, its agent and its grant are active, then signs a token for that one resource and the granted scopes, with a private key only it holds. This is the point at which current permissions are consulted.
  4. The platform verifies the token against MudraID’s public keys — on its own, without calling MudraID per request.
  5. The platform checks the scope the route requires against the scopes in the token.
Step 4 is local verification, so MudraID does not see it and does not record it. What MudraID records is what passes through it: every token issuance and every failed client authentication. Under live enforcement it also records each /decide outcome, because in that mode the decision is made by MudraID.

​
The key insight: key in, token out

The client’s private key never leaves your environment, and never reaches the platforms it calls. The SDK uses it to sign a one-time assertion, exchanges that for a token, and only the token travels onward. The platform only ever sees something it can verify by itself. That separation is what makes the model safe:
  • A platform can’t leak your key, because it never had it.
  • A token stops working once it expires — five minutes after issuance by default.
  • Verification needs no shared secret between you and the platform — just MudraID’s public keys.

​
Why tokens are short-lived

Under offline verification the token’s lifetime is the containment window, because that is how long a surface validating locally will keep honouring a token it has already been given. Access tokens therefore live five minutes by default and never longer than the configured fifteen-minute ceiling. Permission changes, suspension and credential revocation prevent 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 on each protected action. The other benefits hold in both modes: you never have to rotate a long-lived shared secret across every caller at once, and a captured token is worth little because it ages out on its own and only works at the one resource it was minted for.

​
A worked example

A travel agent calls an airline’s booking API.
  1. The agent has been granted flights:search and flights:book on that airline.
  2. It calls GET /flights. The SDK fetches a token carrying those scopes and attaches it.
  3. The airline’s middleware verifies the token and sees flights:search is present — the request is served.
  4. Later the agent calls POST /bookings, which requires flights:book. The token carries it, so that’s served too.
  5. If the airline revokes the agent, MudraID stops issuing it tokens for that airline straight away. The token already in the agent’s hands keeps working against the airline’s offline check until it expires — under five minutes on the default lifetime. Had the airline been running live enforcement, the next protected action would have been refused, because that mode asks MudraID at the time of the call.

​
Where to go next