ZipPigeon technical whitepaper Updated Aug 2, 2026 3 min read

Choose the right service principal

Use a Secure File Bridge for ordinary upload, share, and download automation. Use an AI agent principal only for owner-approved access to exact case artifacts. The two principal types have separate scope families, so an ordinary service cannot become an agent because an old token happens to contain an agent scope.

  • Secure File Bridge: uploads:create, uploads:complete, uploads:read, shares:create, shares:revoke, and downloads:read.
  • AI agent: agent_access:request and agent_access:consume only.
  • Create, token-issuance, federation-binding, and revocation operations remain step-up-protected account actions.

Establish and store credentials

Create the principal in Account → Service API, install the one-time encrypted configuration with the standalone CLI, and move its token, key bundle, and bundle passphrase into a backend secret manager. ZipPigeon stores an HMAC hash of the API token; the raw token and encrypted private-key bundle are shown only during setup.

zippigeon configure --paste
zippigeon doctor

# Inject at runtime from a secret manager
export ZIPPIGEON_KEY_PASSPHRASE="<runtime-secret>"

Manage the identity lifecycle

Service-account administration uses the signed-in sponsor session rather than a service credential. Creating a principal, issuing a replacement token, binding external identity, and other sensitive changes require recent step-up where applicable. Token deletion revokes one credential; service-account deletion revokes the whole machine identity.

POST   /api/service-accounts
GET    /api/service-accounts
POST   /api/service-accounts/:id/tokens
DELETE /api/service-accounts/:id/tokens/:tokenId
DELETE /api/service-accounts/:id

Sign every API request

A service request combines the scoped bearer token with proof from the service signing key. The signature binds the service account ID, HTTP method, path including query, timestamp, unique nonce, and SHA-256 body digest. The server rejects expired timestamps, replayed nonces, invalid signatures, revoked or expired tokens, and missing scopes.

Authorization: Bearer zp_api_...
x-zippigeon-service-id: service_account_id
x-zippigeon-timestamp: 2026-08-02T12:00:00.000Z
x-zippigeon-nonce: unique_random_value
x-zippigeon-signature: versioned_base64url_signature

Reduce privilege with scopes and rotation

Issue a token with only the operations one workload needs and give it a finite expiration. Rotate by creating a replacement, verifying the new credential, moving the workload, and revoking the old token. Revoking a token is narrower than deleting its service account; deleting the principal ends every credential attached to that identity.

  • An uploader that never downloads should not receive downloads:read.
  • A reporting job that only lists service-owned transfers can use uploads:read.
  • Separate production, staging, and partner workloads so one revocation does not interrupt unrelated jobs.

Migrate cryptography without replacing file blobs

Existing file-backed service configurations can migrate to v3 X-Wing key protection and Ed25519 + ML-DSA-65 request signatures. The ceremony proves possession of the new decapsulation key before publication, preserves eligible API tokens, and can rewrap historical data-encryption-key envelopes without re-encrypting stored file ciphertext.

POST /api/service-accounts/crypto-migration/challenge
POST /api/service-accounts/crypto-migration

zippigeon service migrate --passphrase "$SERVICE_KEY_PASSPHRASE"
# Add --skip-data to defer historical envelope rewrapping.

Benefits and use cases

This model gives integrations defense beyond a long-lived bearer secret: route-level authorization, request integrity, freshness, replay resistance, and a separately revocable workload identity. It fits CI export delivery, scheduled reporting, partner file bridges, support evidence pipelines, and internal services that need an auditable machine principal.

  • CI/CD: isolate a release-artifact sender from human accounts.
  • Partner bridge: give each partner its own scopes, expiration, and revocation boundary.
  • Scheduled export: sign and encrypt generated reports before they leave the job runner.