Workload Identities
Not everything that calls your platform is a person. A background service syncs records, a CI job deploys on every merge, an agent reaches for a tool mid-task. The usual answer — hand each one a long-lived API key, or let it borrow a human's credentials — is the usual source of breaches: a leaked key is a standing invitation, and a machine acting as a person muddies every audit trail it touches.
A workload identity is a first-class machine principal: a service, job, or agent authenticates as itself, with credentials suited to a machine rather than a login. It's not a member of your role hierarchy — a workload has no roles. Its authority is exactly the scope you granted it at registration, and nothing it presents at runtime can widen that.
Two kinds
Workload identities come in two variants, and the variant is fixed the moment you create one — it's written into the identity's ID prefix and can never change. Moving from one to the other means enrolling a new identity, not upgrading in place.
| Software Workload Identity (SWI) | Confidential Workload Identity (CWI) | |
|---|---|---|
| ID prefix | swi_ | cwi_ |
| Proves it's genuine by | possessing a registered key, or a trusted external token | a hardware attestation of the environment it runs in |
| Runs in | any environment | a hardware-isolated Trusted Execution Environment (TEE) |
| Reaches assurance tier | up to T3 (phishing-resistant key possession) | T4 (hardware-attested) — the platform's highest |
| Best for | services, CI/CD jobs, agents on ordinary infrastructure | workloads that must prove where and how they run before touching the most sensitive keys and data |
Once authenticated, a workload's token has this shape: a short-lived platform JWT whose sub is the workload's ID, a scope claim listing exactly the operations you granted it, and an optional tag you supply to correlate one running instance across re-authentications in the audit trail. There is no roles claim — a workload's authority is its scope, evaluated at the point of use, never a seat in the role lattice.
Software Workload Identity
An SWI authenticates one of two ways, chosen when you create it.
Bound-key. You register a key — a DPoP public key or an mTLS client certificate — and the workload proves possession of it on every call. The key is the credential; there's nothing else to leak, and a captured request can't be replayed without the key that signed it. This is the path for a service or agent you run on your own infrastructure.
Federation. For a workload that already has an identity from an external issuer — a GitHub Actions job, a cloud CI runner, any OIDC provider — you register the trust relationship (issuer, audience, and the claims that must match) instead of a key. The workload presents its external OIDC token and exchanges it for a short-lived platform token:
POST <orgSlug>.api.k9o.io/@<projectSlug>/workloads/<swi-id>/token
DPoP: <RFC 9449 proof JWT>
{ "oidcToken": "<the external OIDC JWT>", "tag": "<optional correlation label>" }
Only a federated SWI can use this route. The default proof of possession is DPoP, so the request must carry an RFC 9449 proof in the DPoP header; without it the call fails with K9O_WORKLOAD_FEDERATION_TOKEN_INVALID (reason dpop_proof_absent). The platform verifies the presented token against the issuer's live JWKS and the trust rules you registered, then mints a platform workload JWT scoped to that workload. Nothing long-lived is ever stored on the runner — the external identity it already has is the credential. A token from an unreachable issuer fails closed (K9O_WORKLOAD_FEDERATION_ISSUER_UNREACHABLE, 503) rather than falling back to stale keys; one that fails verification returns K9O_WORKLOAD_FEDERATION_TOKEN_INVALID (401).
Confidential Workload Identity
A CWI proves something an SWI cannot: not just who it is, but where and how it is running. It's for workloads that must demonstrate they execute inside a genuine, unmodified, hardware-isolated environment before the platform will release its most sensitive keys to them — the same integrity guarantee behind Kibo's SKR custody mode, applied to identity.
A CWI is bound at registration to a measurement policy — a declared allowlist of the exact code measurements and minimum trusted-computing-base versions you authorize. A CWI can never be federated: its identity is its attestation, and accepting an external issuer's say-so instead would defeat the guarantee.
A CWI can be registered, listed and revoked (see Managing workloads). This page documents no token request for a CWI.
Assurance tiers
Where a workload lands on the platform's assurance ladder follows directly from how it authenticated:
| Tier | What it means | Reached by |
|---|---|---|
T3_KEY_POSSESSION | Phishing-resistant key possession | A bound-key or DPoP-federated SWI |
T4_HW_ATTESTED | Hardware-measured identity | A CWI, and only a CWI |
Policies that gate an operation behind a minimum tier compose cleanly with this: a rule demanding T4_HW_ATTESTED can be satisfied only by a genuine hardware attestation, so declaring it against a workload that can't produce one is caught as an authoring error, not a silent runtime denial. (The full ladder, including the human step-up tiers below T3, is in Unified Policy → requires_proof.)
Managing workloads
Workloads are created and revoked by an operator, through one small set of endpoints:
POST <orgSlug>.api.k9o.io/@<projectSlug>/workloads — create (display name + variant + its credential)
GET <orgSlug>.api.k9o.io/@<projectSlug>/workloads — list (filter with ?status=active|revoked|all; default active)
GET <orgSlug>.api.k9o.io/@<projectSlug>/workloads/<id> — read
DELETE <orgSlug>.api.k9o.io/@<projectSlug>/workloads/<id> — revoke immediately
The create body is { displayName, variant, ... } with variant set to "CWI" or "SWI" (upper case). The variant you declare must match the credential you supply — a CWI needs a measurementPolicyId, an SWI needs a boundKey or a federationTrust (with an optional swiMode) — and a mismatch is refused at creation (K9O_WORKLOAD_VARIANT_MISMATCH, 400). Creation and revocation both emit signed audit events (data.write.auth.workload.created / .revoked), so the roster of machine principals in a project is itself part of the forensic record. Revocation takes effect immediately; because a workload has no human membership, there's no cascade to wait on.
See also
- Kibo SKR — the custody mode that releases keys only to attested code, the same integrity guarantee a CWI carries into identity.
- Unified Policy →
requires_proof— gating operations on a minimum assurance tier. - Gate overview — the identity plane workload identities live in.