agent — A program, often an AI agent, that calls APIs on someone’s behalf. In MudraID it has its own verifiable identity.
platform — A service or API that agents call and that protects its routes with MudraID. Identified by a platform_id.
SDK — The library an agent uses (mudraid-sdk). Its MachineAgent authenticates a linked OAuth client and attaches access tokens to every call, returning ordinary requests responses.
middleware — The library a platform uses (mudraid-platform-middleware). It verifies tokens and enforces scopes before requests reach your handlers, or, in V2 mode, asks /decide about each MCP tool call.
OAuth machine client — The credential-holding principal linked to an agent. It authenticates at /oauth2/token with private_key_jwt (a key you hold) or, with an organization approval, client_secret_basic.
private_key_jwt — Client authentication by a short-lived assertion signed with the client’s registered key (RS256 or ES256). The private key never leaves your environment.
grant — An approval for one client to use one resource with specific scopes. Linking a client to an agent grants nothing on its own.
resource — The exact URI an access token is requested for. It becomes the token’s audience (aud).
pepper — A server-side secret value MudraID mixes into every stored secret hash, so a stolen database can’t be turned into usable credentials. Managed by MudraID; nothing you configure.
platform_id — The unique id for a platform, used in its scopes file and portal records.
scope — A permission string, by convention resource:action (e.g. items:read). A route requires a scope; a token carries the ones its agent was granted. Scopes are flat — no implicit hierarchy.
mudraid_scopes.yaml — A platform’s configuration file mapping each route to a required scope, a public bypass, or a hidden skip (404). Generated by the MudraID portal.
public route — A route marked public: true that needs no token (e.g. a health check).
skip route — A route marked skip: true that returns 404 and is invisible to agents.
access token — The short-lived, signed RFC 9068 JWT (typ: at+jwt) an agent presents to a resource. Audience-bound to one resource and carrying the granted scope. Expires in minutes.
JWKS — The set of public keys MudraID publishes so platforms can verify token signatures without contacting MudraID per request.
kid — The key id on a token, naming which signing key produced it. The middleware fetches fresh keys when it sees an unfamiliar kid.
aud / iss / exp / nbf / iat — Standard JWT claims — audience, issuer, expiry, not-before, issued-at — all checked during verification.
verification — The platform-side check that a token is genuine, current, meant for this platform, and carries the required scope. Under offline verification this happens entirely inside your middleware, against MudraID’s published keys.
offline verification — The mode in which your middleware validates an access token locally against JWKS and MudraID is not called while the request is served.
live enforcement — The mode in which an enforcement adapter asks MudraID’s /decide about each protected action, which resolves current grants, authority, containment, entitlement and policy. It uses the same access token.
/decide — MudraID’s decision endpoint. Answers allow, deny or not_safely_decided, and is deny-closed: anything it cannot decide safely is refused.
enforcement adapter — The component in front of your protected actions that calls /decide: the middleware’s V2 mode, the Node adapter or sidecar, or the Kong plugin.
containment — Stopping an agent, client, grant or surface in steps: quarantine (reversible), suspension (can be lifted), revocation (terminal).
revoke — Cut an agent off. Revoking its grant 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 on each protected action.
rotate — Replace a client’s signing key or client secret, with an overlap so traffic doesn’t break during the swap.
audit log — MudraID’s append-only, tamper-evident record of what passes through it: token issuance, failed authentications, and live-enforcement decisions. Offline verification is local to your middleware and is not recorded there.
Production Proof — A signed bundle of evidence about your integration that a reviewer can verify offline against MudraID’s published proof-signing keys, shared through a revocable link.
