Python SDK

ZeroIDClient for Python — agent registration, token issuance, local and online JWT verification, delegation, and CAE signals.

Use the Python SDK when you want the fastest path to integrating ZeroID into a developer tool, backend service, or agent runtime.

The Python client wraps both admin workflows and public token workflows in a single ZeroIDClient.

Choosing the Right Method

I want to...	Use
Register a new agent	client.agents.register()
Get an access token from an API key	client.tokens.issue(grant_type="api_key", ...)
Verify a token fast (no network, no revocation check)	client.tokens.verify()
Verify a token and check for revocation	client.tokens.session()
Verify from a raw Authorization: Bearer ... header	client.tokens.verify_bearer() or client.tokens.session_from_request()
Delegate authority to a sub-agent	client.tokens.delegate()
Check if a token is still active (online)	client.tokens.introspect()
Invalidate a token	client.tokens.revoke()
Ingest a CAE signal (e.g. session revoked)	client.signals.ingest()
Control what grant types and delegation depths are allowed	client.credential_policies.create()

verify() vs session()

	tokens.verify()	tokens.session()
Network call	No — uses cached JWKS	Yes — calls introspection endpoint
Reflects revocation	Not until JWKS rotates	Immediately
Latency	~1ms (local)	~20–50ms (network)
Returns	ZeroIDIdentity	AgentSession
require_scope() / require_trust()	No	Yes
Use when	Service mesh, hot path, high throughput	User-facing endpoints, high-security decisions

When in doubt: use verify() inside your service mesh where revocation lag is acceptable, and session() at your public API boundary where you need real-time revocation awareness.

Installation

pip install highflame

For delegation examples that build signed assertions locally:

pip install cryptography PyJWT

Create a Client

from highflame.zeroid import ZeroIDClient

client = ZeroIDClient(
    base_url="http://localhost:8899",
    account_id="acct-demo",
    project_id="proj-demo",
)

For local development, you can omit account_id and project_id and let the client generate them.

Available Resources

Current Python resources:

• client.identities

• client.agents

• client.oauth_clients

• client.credential_policies

• client.api_keys

• client.tokens

• client.signals

Convenience methods:

• client.health()

• client.jwks()

Register an Agent

registered = client.agents.register(
    name="Data Fetcher",
    external_id="data-fetcher",
    sub_type="tool_agent",
    trust_level="first_party",
    created_by="[email protected]",
)

print(registered.identity.id)
print(registered.identity.wimse_uri)
print(registered.api_key)

Use client.identities instead when you want lower-level identity control instead of the higher-level agent registration convenience API.

Issue a Token

token = client.tokens.issue(
    grant_type="api_key",
    api_key=registered.api_key,
)

print(token.access_token)
print(token.expires_in)

Introspect and Revoke

info = client.tokens.introspect(token.access_token)
print(info.active)

client.tokens.revoke(token.access_token)

Delegate to a Sub-Agent

If the client was initialized with an API key, the Python SDK can automatically use the cached access token as the subject_token:

delegated = client.tokens.delegate(
    actor_token=actor_token,
    scope="data:read",
)

This is the cleanest way to implement orchestrator to sub-agent delegation from Python.

Verify a Token Locally

Use tokens.verify() or tokens.verify_bearer() to validate a JWT using ZeroID's JWKS without a network round-trip to the introspection endpoint.

Use verify() when you need low latency and can tolerate a brief window where a revoked token still passes (until the next JWKS rotation). Ideal for service-to-service calls inside a trust boundary.

# From a raw token string
identity = client.tokens.verify(token.access_token)

# From an Authorization header value
identity = client.tokens.verify_bearer(request.headers["Authorization"])

print(identity.sub)
print(identity.trust_level)

The returned ZeroIDIdentity object includes helper methods:

identity.has_scope("data:read")   # bool
identity.has_tool("bash")         # bool
identity.is_delegated()           # bool — True if act.sub is present
identity.delegated_by()           # str | None — the orchestrator sub

Async variants: averify(), averify_bearer().

Session Verification (Introspection-Based)

Use tokens.session() or tokens.session_from_request() for an online check that reflects the latest revocation state.

Use session() when you need immediate revocation awareness — e.g. at a public API boundary or before a high-risk action. It makes a network call to the introspection endpoint. require_scope() and require_trust() (which raise on failure) are only available on AgentSession, not on ZeroIDIdentity.

# From a raw token string
session = client.tokens.session(token.access_token)

# From request headers (reads the Authorization: Bearer ... header)
session = client.tokens.session_from_request(request.headers)

if not session.active:
    # token revoked or expired
    pass

session.has_scope("data:read")         # bool
session.require_scope("data:read")     # raises if scope missing
session.is_delegated()                 # bool
session.delegated_by()                 # str | None
session.require_trust("first_party")   # raises if trust level below minimum

Async variants: asession(), asession_from_request().

Manage Policies

policy = client.credential_policies.create(
    name="tool-agent-policy",
    max_ttl_seconds=600,
    allowed_grant_types=["token_exchange"],
    allowed_scopes=["data:read"],
    required_trust_level="first_party",
    max_delegation_depth=0,
)

Manage Signals

signal = client.signals.ingest(
    signal_type="session_revoked",
    severity="critical",
    source="runtime-monitor",
    identity_id=registered.identity.id,
    payload={"reason": "suspicious tool use"},
)

Recommended Usage Pattern

For most Python services:

1. create one ZeroIDClient per process

2. set explicit tenant IDs in non-local environments

3. use client.agents.register() for first registration flows

4. use client.tokens.issue() for direct auth

5. use client.tokens.delegate() for delegation

When To Drop Down To REST

Today, use REST directly if you need a server feature that has not yet been surfaced through Python resources, such as a newly added admin endpoint.