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). A drop-in replacement for requests that authenticates every call.
middleware — The library a platform uses (mudraid-middleware). It verifies tokens and enforces scopes before requests reach your handlers.
api_key_id — An agent’s public identifier. Prefix muid_kid_. Safe to log and share.
secret — An agent’s private credential. Prefix muid_sk_. Shown once at registration, stored only as a one-way hash, and never logged.
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. A token’s audience (aud) must match it, which is what binds a token to one platform.
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.
token (JWT) — The short-lived, signed credential an agent presents instead of its secret. Verified by the platform on its own. 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.
revoke — Cut an agent off immediately. It receives no new tokens; any token already issued expires within minutes.
rotate — Replace an agent’s secret with a new one, keeping the old valid briefly so traffic doesn’t break during the swap.
audit log — MudraID’s append-only, tamper-evident record of every verification, used to prove what happened after the fact.
