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.

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.

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.

Deployment guardrails

Workload federation is optional and fails closed unless delegated access and the federation configuration are enabled. Use an HTTPS exact audience, bounded assertion and credential lifetimes, publicly verifiable identity keys, outbound JWKS protections, rate limits, and deployment readiness checks before exposing the exchange route.

AGENT_DELEGATED_ACCESS_ENABLED=true
AGENT_WORKLOAD_FEDERATION_ENABLED=true
AGENT_WORKLOAD_AUDIENCE=https://files.example.com/api/agent-workload/token
AGENT_WORKLOAD_TOKEN_TTL_SECONDS=300