ZipPigeon technical whitepaper Updated Aug 2, 2026 3 min read

Bind one exact workload identity

A sponsor with recent step-up verification binds either an exact SPIFFE/SPIRE JWT-SVID subject or an exact enterprise OIDC issuer and subject to one AI agent. The binding includes an operator-approved public JWKS URL, algorithm, audience, and identity details rather than accepting identity metadata supplied by each request.

  • SPIFFE: exact spiffe:// subject, trust domain, bundle JWKS URL, and RS256 or ES256.
  • Enterprise OIDC: exact HTTPS issuer, subject, JWKS URL, and RS256, ES256, or EdDSA.
  • Binding immediately revokes the bootstrap static token.

Exchange once for a short-lived credential

The workload obtains a fresh signed assertion from its identity system and sends it once to POST /api/agent-workload/token. ZipPigeon validates the configured issuer, subject, audience, algorithm, provider key, expiry, bounded lifetime, and assertion replay before returning a short-lived zp_wid_ credential with no refresh token.

Command 
POST /api/agent-workload/token

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token_type=urn:ietf:params:oauth:token-type:jwt
subject_token=<fresh signed assertion>
service_account_id=<agent id>
audience=<exact configured audience>
scope=agent_access:request agent_access:consume

Retain proof of the agent key

The exchanged bearer credential does not replace ZipPigeon request signing. Every delegated-access call still binds its method, path, body digest, timestamp, nonce, and service account ID to the agent signing key. An attacker therefore needs both an eligible short-lived credential and the correct agent key proof.

  • Use the existing encrypted agent key bundle with each exchanged credential.
  • Acquire a new external assertion after the temporary credential expires.
  • Do not turn the exchanged credential into a long-lived secret or persist it in logs.

Make identity changes invalidate access

Replacing or removing the workload binding, completing proven agent-key migration, or revoking the agent invalidates exchanged credentials and outstanding delegated access. This keeps the authorization record bound to the identity and key generation the owner actually reviewed.

Command 
PUT    /api/service-accounts/:id/workload-identity
DELETE /api/service-accounts/:id/workload-identity
POST   /api/agent-workload/token

Benefits and use cases

Federation removes the need to distribute a reusable agent bearer token across modern workload platforms. It fits Kubernetes workloads with SPIRE, enterprise jobs with OIDC workload identities, short-lived incident responders, and MCP gateways that already obtain identity assertions from an authorization system.

  • Kubernetes: map a single SPIFFE workload identity to one sponsored ZipPigeon agent.
  • Cloud or enterprise job: exchange a fresh OIDC assertion at runtime instead of mounting a static API token.
  • Credential response: replace the binding or key generation to invalidate previously issued access.

Security prerequisites

ZipPigeon enables and operates workload federation only after its trust configuration is ready. Customer administrators provide the exact enterprise identity binding through the supported account workflow; they do not configure ZipPigeon server flags. The service applies an exact HTTPS audience, bounded assertion and credential lifetimes, public-key retrieval protections, replay checks, and rate limits before accepting an exchange.