API Keys vs Scoped AI Agent Grants

Use API keys as service credentials; use verifiable grants when a service must know which agent may do what for which principal.

API keys are not inherently unsafe. They are often the right credential for a tightly controlled service integration. Risk rises when a broad key is copied into autonomous agents, shared across agents, or used where a person expects explicit, revocable delegation.

What changes with an agent grant?

Decision	API key	Grantex grant
Identity represented	Usually an account, project, or integration	Agent DID, principal, and grant identifiers in a signed token
Permissions	Provider-defined key roles or scopes	Narrow grant scopes that the receiving service must enforce
Lifetime	Provider-dependent; keys may be long-lived	Time-limited JWT with explicit expiry
Delegation	Copying a key does not attenuate authority	A child grant must be a narrower scope subset and records delegation depth
Revocation	Rotating a shared key affects every consumer	Revoke a grant centrally; local verifiers still need current state
Audit context	Provider logs may identify the key	Optional audit records can attribute actions to agent, grant, and principal

When an API key is still appropriate

A backend service owns the credential and never exposes it to a model or agent process.
The provider's native key scopes and rotation controls match the risk.
No per-user or per-agent delegation decision must be proven to the receiving service.

When to add Grantex

Several agents share one application but require different permissions.
An agent acts for a human or organization and the service needs that principal context.
Sub-agents must receive a narrower subset of a parent agent's authority.
Individual grants need expiry, central revocation, or attributable audit records.

Incremental migration

Keep provider secrets in the receiving backend rather than in the agent prompt or tool runtime.
Register each agent and request only the scopes required for its task.
Send the Grantex grant token to the service that owns the protected action.
Verify the token signature and claims, then enforce the required scope before using the provider credential.
Add online or synchronized grant-state checks where immediate revocation matters.

app.post(
  '/calendar/events',
  requireGrantToken({
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  }),
  requireScopes('calendar:write'),
  createCalendarEvent,
);

Local JWT verification checks signatures and claims after JWKS retrieval. It does not prove current revocation unless the verifier performs an online state check or synchronizes revocation data.

Replace broad agent credentials one boundary at a time

Start with the action whose misuse would have the highest impact.

Open the quickstart

Technical review updated 12 July 2026.