Claw

---

import clawid_sdk_sdk

result = clawid_sdk.verify(token)
if result.valid:
    print(result.agent_id, "owned by", result.tenant_id)

That's it. Three lines. Free forever for verifiers. No key, no contract.

What is this?

ClawID is the trust layer for autonomous AI agents and the services they touch. Every agent carries a Claw — a cryptographically signed credential that binds the agent to its owner, declares the owner's policy (the leash), and produces a tamper-evident receipt of every action. This SDK is what services use to verify a Claw on the way in.

When an AI agent calls your API, you want to know:

• Who's behind it? → result.tenant_id, result.agent_id
• What did the owner permit? → result.leash
• Can the owner kill it? → yes; result.status reflects current revocation state
• Is there a record of the attempt? → yes; every check-in lands in a hash-chained audit log on both sides

One round-trip, four answers. Free forever for verifiers.

Install

pip install clawid-sdk

Python 3.10+. Two dependencies: httpx and pyjwt[crypto].

Use

The common case

import clawid_sdk

result = clawid_sdk.verify(token)

if not result.valid:
    return reject(result.status, result.reason)

# Now you know who this is.
print(f"Agent {result.agent_id} owned by {result.tenant_id}")
print(f"Leash: {result.leash}")

When you want to configure things

from clawid_sdk import Claw

claw = Claw(
    hub_url="https://api.holdtheleash.id",   # defaults to this
    jwks_ttl=300,                             # cache the hub's pubkey for 5 minutes
    timeout=5.0,                              # per-request timeout
)

result = claw.verify(token)

Async

result = await clawid_sdk.verify_async(token)

Offline mode (signature + expiry only, no live revocation check)

result = clawid_sdk.verify(token, mode="offline")

Use when latency matters more than seeing revokes immediately. The signature check still uses the cached JWKS, so signature validity is accurate. Revocation is NOT checked in offline mode — you won't see a revoke until you either fall through to online mode for a call, or poll /v1/verify for the token's jti out of band on a schedule you control. Suited for very high-throughput verifiers who accept explicit revocation lag in exchange for zero network round-trips per verify.

Web-framework integration

The SDK is framework-agnostic by design. A FastAPI middleware looks like:

from fastapi import FastAPI, HTTPException, Request, Depends

import clawid_sdk

app = FastAPI()

def claw_required(request: Request) -> clawid.VerifyResult:
    auth = request.headers.get("Authorization", "")
    token = auth.removeprefix("Bearer ").strip()
    if not token:
        raise HTTPException(401, "missing Claw")
    result = clawid_sdk.verify(token)
    if not result.valid:
        raise HTTPException(401, f"{result.status.value}: {result.reason}")
    return result

@app.post("/charge")
def charge(amount: float, agent: clawid.VerifyResult = Depends(claw_required)):
    if amount > agent.leash["spend_ceiling"]:
        raise HTTPException(403, "amount exceeds agent's leash")
    return {"agent_id": agent.agent_id, "charged": amount}

Push notices

The hub can POST to your server when something changes — a Claw used on your service was revoked, or (for owners) an agent is waiting for approval. Register an endpoint in the dashboard (Settings → Push notices) or with POST /v1/webhooks. Each notice is a signed Security Event Token (Content-Type: application/secevent+jwt), checked against the same public key as every Claw:

import clawid_sdk

result = clawid_sdk.verify_event(request_body, audience="tnt_your_tenant_id")
if result and result.event_type == "claw.revoked":
    forget(result.data["claw_jti"])        # stop honoring this Claw now

event_type	Who gets it	data
claw.revoked	verified vendors the Claw was used on	claw_jti, agent_id, tenant_id, revoked_at, cause (owner / auto_revoke)
hold.created	the owner	hold_id, agent_label, surface, action, amount, expires_at, approve_url
hold.resolved	the owner	hold_id, status (approved / rejected), release_expires_at
ping	whoever pressed "Send test"	endpoint_id, sent_at

Failed deliveries are retried for about a day and a half, so the same notice can arrive twice: dedupe on result.event_id. Push is a speed-up, not the source of truth — verify(token) in online mode still asks the hub live.

What the result tells you

VerifyResult is a dataclass. if result: is shorthand for if result.valid:.

@dataclass
class VerifyResult:
    valid: bool                     # True iff the Claw is currently usable
    status: VerifyStatus            # ACTIVE | REVOKED | EXPIRED | INVALID | UNKNOWN
    reason: str | None              # human-readable reason
    jti: str | None                 # JWT id of this Claw (stable receipt key)
    agent_id: str | None            # who the agent is
    tenant_id: str | None           # who owns the agent
    leash: dict | None              # the owner's policy: spend cap, surfaces, hours...
    agent_pubkey_pem: str | None    # for proof-of-possession on signed actions
    issued_at: int | None
    expires_at: int | None
    payload: dict | None            # raw decoded JWS payload, for custom claims

VerifyStatus:

This is the beginning of the README. Read the rest at the original. Read the full README ↗