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
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, andsession()at your public API boundary where you need real-time revocation awareness.
Installation
For delegation examples that build signed assertions locally:
Create a Client
For local development, you can omit account_id and project_id and let the client generate them.
Available Resources
Current Python resources:
client.identitiesclient.agentsclient.oauth_clientsclient.credential_policiesclient.api_keysclient.tokensclient.signals
Convenience methods:
client.health()client.jwks()
Register an Agent
Use client.identities instead when you want lower-level identity control instead of the higher-level agent registration convenience API.
Issue a Token
Introspect and Revoke
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:
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.
The returned ZeroIDIdentity object includes helper methods:
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.
Async variants: asession(), asession_from_request().
Manage Policies
Manage Signals
Recommended Usage Pattern
For most Python services:
create one
ZeroIDClientper processset explicit tenant IDs in non-local environments
use
client.agents.register()for first registration flowsuse
client.tokens.issue()for direct authuse
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.
Last updated