Identity

Soul Stack has two kinds of principals, and each proves its identity in its own way:

• managed hosts (Souls) — via an mTLS certificate whose private key never leaves the host;
• operators (Archons) — via a JWT bound to an AID identifier.

Host identity (Soul)

A managed host’s identity is built on three entities.

SID = FQDN

A host’s identifier (SID) is its FQDN, not a random UUID. Consequences:

• reinstalling the agent on the same host deduplicates automatically — the SID matches, so no new record is created;
• renaming the FQDN is treated as a migration (old host → new host); changing the SID “in place” is not supported.

SoulSeed

SoulSeed is the “mTLS certificate + private key” pair the agent authenticates with when connecting to the Keeper.

• The private key is generated on the host itself and never leaves it. Only the signing request (CSR) goes out.
• SoulSeed is rotated regularly over the live stream, without operator involvement.
• The Keeper’s database stores only the certificate fingerprint — no PEM, and certainly no private key.

The main cryptographic protection of identity is the certificate authority (CA) private key, which lives in Vault rather than on the cluster’s disks.

Coven

Coven is an arbitrary, stable label for grouping hosts logically (by data center, project, or environment). It is used in RBAC (scoping an operator’s permissions by covens) and in task targeting. Coven has nothing to do with proving identity — it is a grouping, not an identifier.

CSR onboarding

The agent’s first connection exchanges a one-time bootstrap token for a permanent mTLS identity. At no step is the private key sent over the network.

1. The operator registers the host and receives a short-lived bootstrap token — a single-use token, not a certificate and not a key.
2. The token is delivered to the host together with the agent binary (the delivery method is the operator’s choice).
3. On the host, the agent:
   • generates a private key locally (it will never leave the host);
   • builds a CSR (certificate signing request);
   • presents the token and CSR to the Keeper on a separate bootstrap listener (server-only TLS);
   • receives a signed certificate — the SoulSeed;
   • stores the certificate next to the private key and burns the token;
   • opens the main gRPC stream, now using the SoulSeed as its mTLS identity.

Bootstrap token protections

The token is the most sensitive moment of onboarding (it is the pass to obtaining a signed certificate), so it is wrapped in three protections:

• Single use. The token is burned on the first successful CSR presentation; it cannot be reused.
• Short TTL. The token lives for a limited time (24 hours by default) and expires if unused.
• SID binding. The token is valid only for the host it was issued for.

The database stores not the token itself but its hash — even with database access, a valid token cannot be reconstructed.

Why the private key stays on the host

Because the private key is generated locally and never travels over the network, it cannot be intercepted in transit and cannot be extracted from the Keeper’s database — it simply isn’t there. The only way to compromise a given host’s identity is to gain access to the host itself.

Operator identity (Archon)

A Soul Stack operator is called an Archon. Its identifier is the AID (Archon ID).

• AID — a stable string identifier for the operator (for example, archon-alice, archon-ops-01). This is the identifier the operator appears under in the audit log and in role bindings.
• Credential — JWT. The operator presents a signed JWT to the Operator API. The signing key lives in Vault.
• The first Archon is created by a separate Keeper administrative command when the cluster is initialized and receives the cluster-admin role. All subsequent Archons are created through the Operator API by an existing administrator.
• Revocation. An Archon can be revoked; with a short token TTL, this gives fast access cutoff.

The full operator permission model — roles, the permissions catalog, groups (Synod), and scoped visibility (Purview) — is in Operator management.

Push mode: identity without mTLS

In push mode (managing a host over SSH with no agent installed), the host has no mTLS identity — the SSH side plays that role (SSH keys and authentication). Such a host is a record in the same registry marked transport: ssh; no SoulSeed is issued for it. More on the transport for both modes — Transport.