Skip to content

Workloads

A Workload is a registered application or service that authenticates to retrieve secrets at runtime via an API call. Unlike Couriers (which write secrets to files) or Bridges (which cache secrets in memory for local consumers), Workloads call an API endpoint to retrieve secrets on demand — making them well-suited for applications that need to resolve secrets dynamically rather than at startup.

Workloads can authenticate against two targets:

  • Zaita SaaS — the cloud platform, reached at https://<tenant>.zaita.io. Requires live platform connectivity on every call.
  • A Bridge — an on-premises agent that exposes the same API endpoints and serves secrets from its local in-memory cache. Does not require a live SaaS connection at retrieval time.

Role required: Managing Workloads requires the Secrets Administrator or Super Administrator role.

Authentication Methods

Workloads support six authentication methods. The appropriate method depends on where the Workload runs and what identity infrastructure is available.

Method Best For
client_secret Simple environments; applications with no cloud identity provider
pki_certificate Environments with existing X.509 PKI infrastructure
azure_jwt Applications running in Azure with Managed Identity or Workload Identity Federation
azure_arc Workloads running on Azure Arc-enrolled on-premises or edge servers
spiffe_spire Service meshes and environments using SPIFFE/SPIRE for workload identity
oidc_oauth2 Applications using a generic OIDC/OAuth2 identity provider

Where possible, prefer the credential-less methods (azure_jwt, azure_arc, spiffe_spire, oidc_oauth2) over client_secret and pki_certificate. Credential-less authentication eliminates the need to rotate long-lived secrets and reduces the risk of credential leakage.

See Authentication for configuration details for each method.

Workload API Endpoints

Once registered and granted access, a Workload can call the following endpoints to retrieve secrets. These endpoints are identical whether the target is the SaaS platform or a Bridge — only the base URL changes.

Method Endpoint Description
GET /api/v1/workload/lockers List all Lockers the Workload has access to
POST /api/v1/workload/lockers/{lockerUuid}/download Download secrets from a single Locker
POST /api/v1/workload/lockers/download-all Download secrets from all accessible Lockers

Secrets are returned as plaintext JSON over the TLS-secured connection. The TLS channel (authenticated via the Workload's credentials) provides confidentiality and integrity in transit. No additional encryption layer or public key exchange is required — the Workload can consume the response directly without any local decryption step.

This differs from Courier and Bridge delivery, where secrets are re-encrypted with an ECDH-derived key before leaving the platform so that only the holder of the corresponding private key can decrypt them.

Authenticating Against a Bridge

When a Workload targets a Bridge, it authenticates to https://<bridge-host>/api/v1/workload/... using the same credentials it would use against the SaaS. The Bridge validates the credentials locally using synced credential data (bcrypt hashes, certificate fingerprints, or IdP configuration) received from the platform during its heartbeat cycle.

Access Rule

A Workload can access a Locker via a Bridge if and only if both of the following are true:

  1. The Workload has been granted access to that Locker (via the Locker's Workload Access tab).
  2. That Locker is assigned to the Bridge's cache (via the Locker's Bridge Cache tab).

No additional portal configuration is required. The Bridge automatically serves the intersection of these two existing assignments.

If a Workload requests a Locker that satisfies only one condition — for example, the Locker is cached on the Bridge but the Workload has no access grant — the Bridge returns an authorisation error, and the attempt is logged.

Comparing Delivery Methods

Method Delivery Persistence Requires Live SaaS Connection
Workload → SaaS Direct API call, JSON response None (transient) Yes, on every call
Workload → Bridge API call to Bridge, served from local cache None (transient) No — Bridge cache survives SaaS outages
Courier Written to file on schedule File on disk Yes, on each scheduled run
Bridge (Courier/in-memory) In-memory cache Until Bridge restarts No — cache survives SaaS outages

For guidance on choosing the right delivery method, see Introduction to Secrets Management.

Next Steps