Skip to main content

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 prefixswi_cwi_
Proves it's genuine bypossessing a registered key, or a trusted external tokena hardware attestation of the environment it runs in
Runs inany environmenta hardware-isolated Trusted Execution Environment (TEE)
Reaches assurance tierup to T3 (phishing-resistant key possession)T4 (hardware-attested) — the platform's highest
Best forservices, CI/CD jobs, agents on ordinary infrastructureworkloads 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).

Federated SWIGateExternal issuertoken requestDPoP proof, oidcToken, optional tagfetch live JWKSverify against trust rulesplatform workload JWTsub = workload ID, scope claimrefused, fails closed401 invalid / 503 issuer unreachable
The external token is verified against the issuer's live keys and the registered trust rules before any platform token is minted.

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:

TierWhat it meansReached by
T3_KEY_POSSESSIONPhishing-resistant key possessionA bound-key or DPoP-federated SWI
T4_HW_ATTESTEDHardware-measured identityA 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.