Skip to content
deedglassdocs

intent_required

The agent’s intent mode is required, and the call has no Deedglass-Intent header.

HTTP 403 · permission_error · not retryable

What happened

Section titled “What happened”

The agent’s intent mode is required, and the call has no Deedglass-Intent header. It is 403, never 401: the API key is valid, and a 401 would start an OAuth flow in some MCP clients. MCP clients can’t sign intents in v1, so a required agent can act only through the SDKs or the REST API. The full rules are in INTENTS.md.

Reason Param Message
required Deedglass-Intent Agent "{agent}" requires a signed intent for every call. Send a Deedglass-Intent header; see docs.deedglass.com/intents.
required_mcp Deedglass-Intent Agent "{agent}" requires a signed intent for every call, and MCP clients can't sign intents yet. Call it through the SDK or the REST API, or an admin can set its intent mode to optional in Console › Agents.

required_mcp is the Gate’s answer to a call that arrives through an MCP surface (context.transport is mcp_stdio or mcp_http) for an agent in required mode. Like every identity failure it creates no action: nothing is recorded.

What to do

Section titled “What to do”

Sign each call with the agent’s intent key (pkg/deedglass IntentSigner, or deedglass dev sign-intent to try it) and send the result in Deedglass-Intent. If the agent can’t sign (an MCP client, for example), an admin can set its mode to optional with deedglass agent intent mode <agent> optional.

Example

Section titled “Example”
HTTP 403 · intent_required
{
  "error": {
    "type": "permission_error",
    "code": "intent_required",
    "message": "Agent \"support-bot\" requires a signed intent for every call. Send a Deedglass-Intent header; see docs.deedglass.com/intents.",
    "param": "Deedglass-Intent",
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/intent_required"
  }
}

The message is for a person and can get more exact over time: branch on type and code, never on the message.

In the SDKs

Section titled “In the SDKs”
SDK Raised as
TypeScript (@deedglass/sdk) PermissionDeniedError with code === "intent_required"
Python (deedglass) deedglass.PermissionDeniedError with .code == "intent_required"
Section titled “Related”