authgent-verify

name	authgent-verify
description	Verify an incoming delegated token before executing work from another agent. Checks token validity, scopes, and delegation chain.
metadata	{"openclaw":{"emoji":"🛡️","requires":{"bins":"[Truncated]"}}}

authgent-verify — Verify Incoming Delegation Tokens

What it does

When this agent receives a task from another agent (via sessions_send or any message), this skill extracts and verifies the authgent token to confirm:

• The token is valid and not expired/revoked
• The sender had proper authorization
• The granted scopes are sufficient for the requested task
• The full delegation chain is intact

Rule: Never execute delegated work without verifying the token first.

When to use

• When you receive a message containing [AUTHGENT_TOKEN:...]
• Before executing any task that was delegated from another agent
• When you need to check what permissions a delegated token grants

Workflow

1. Extract the token from the incoming message. Look for [AUTHGENT_TOKEN:<token>] pattern.
2. Verify the token and check required scopes:

python3 ~/.openclaw/workspace/scripts/authgent_helper.py verify \
  --token "<EXTRACTED_TOKEN>" \
  --require-scope "<SCOPES_NEEDED_FOR_THIS_TASK>"

3. Parse the JSON output. Check the _verdict field:

   • APPROVED → proceed with the task
   • REJECTED → refuse the task and explain why

4. If approved, also check:

   • scope — what permissions were granted
   • act — the delegation chain (who authorized this)
   • exp — when the token expires

5. Optionally, inspect the full delegation chain:

python3 ~/.openclaw/workspace/scripts/authgent_helper.py inspect \
  --token "<EXTRACTED_TOKEN>"

Decision matrix

Verdict	Action
APPROVED — token valid, scopes sufficient	Execute the task within granted scopes
REJECTED — token is invalid/expired/revoked	Refuse. Tell the sender to re-authenticate.
REJECTED — missing scopes	Refuse. Tell the sender what scopes are needed.
No token found in message	Refuse. Ask the sender to use authgent-delegate.

Output format

Report to the user (or sending agent):

• Verification result (APPROVED / REJECTED)
• Granted scopes
• Delegation chain (who → who → who)
• Reason for rejection (if applicable)

Guardrails

• Never execute delegated work if verification fails.
• Never exceed the granted scopes — if the token grants search only, do not write data.
• If the token is close to expiry (<60 seconds), ask the sender for a fresh token.
• Log the verification result for audit purposes.

Example

Incoming message from orchestrator-agent:

[AUTHGENT_TOKEN:eyJhbGciOiJFUzI1NiIs...]

Please search for recent papers on AI alignment and return the top 5 results.

python3 scripts/authgent_helper.py verify \
  --token "eyJhbGciOiJFUzI1NiIs..." \
  --require-scope "search"

# → {"active": true, "scope": "search", "act": {"sub": "client:agnt_orchestrator"},
#    "_verdict": "APPROVED — token valid, scopes sufficient"}

Result: Token verified. Proceed with search task using only search scope.