🛡️ Authentication Gates (`authentication-gates`)¶

AuthenticationGatesSkill is the catalog's pattern for handling HTTP 401/403 failures uniformly across every HTTP-using skill. When any other skill returns an auth failure, the agent calls inspect_status_code to classify it, then request_credential_handoff to emit a structured payload that suspends the turn and asks an operator (or another system) for the missing credential. The pattern is recorded in ADR-0005.

When to use it¶

You're shipping any skill that makes outbound HTTP calls and need a uniform auth-recovery story.
Your agent integrates with multiple SaaS APIs (Jira, Salesforce, internal services) that all use OAuth tokens with rotating expiry.
You want a structured contract between the agent and your UI for "ask the user for a credential".

Tools¶

Tool	Purpose
`inspect_status_code`	Classifies a status code; reports `auth_failure: bool`, `scope_required`, and a hint.
`request_credential_handoff`	Emits a `CredentialHandoff` Pydantic event for the operator/UI.

Configuration¶

No environment variables. The handoff payload is fully driven by the arguments the LLM passes to request_credential_handoff.

Handoff payload¶

{
  "type": "credential_handoff",
  "integration": "jira",
  "credential_kind": "api_token",
  "status_code": 401,
  "reason": "token expired",
  "docs_url": "https://example.test/jira-docs"
}

Example — composing with `SecureSkill`¶

from mirai_core.core.types import SecureSkill, SecurityLevel
from mirai_shared_skills.auth_gates import AuthenticationGatesSkill

gated = SecureSkill(
    AuthenticationGatesSkill(),
    policy={
        "inspect_status_code": SecurityLevel.SAFE,             # pure classifier
        "request_credential_handoff": SecurityLevel.REQUIRES_HITL,  # pauses turn
    },
)

The REQUIRES_HITL level on request_credential_handoff is what wires this skill into agent-core's HITL primitive (agent-core ADR-0001).

Security considerations¶

standard per ADR-0001. The skill emits structured signals only — no credentials are stored, transmitted, or accepted by the skill itself. Credential delivery is the calling system's responsibility.

🛡️ Authentication Gates (authentication-gates)¶