How an agent enrolls

An agent’s identity is its signing key, and nothing in the console creates one. This page is the whole lifecycle: how a key enrolls itself, what makes a key unique, and what an owner or admin does when a name needs a new one.

​

Enrollment happens on the first anchor, not before

You write no enrollment step. The first time your agent calls anchor, the SDK proves possession of its signing key to the control plane, and the agent appears on the console’s Agents page under that key. Enrolling is part of what every key can do, so one organization API key covers every agent in your organization. Re-enrolling the same key on a later boot is a no-op, which is what makes it safe to run every time your service starts. See API keys and scopes for what a key carries, and Anchor from your agent for the call itself.

​

Sandbox and live identities

The Sandbox and Live are separate. An agent that enrolls in the Sandbox does not exist in Live, and a signing key enrolled in one is not enrolled in the other. Going live means a fresh enrollment: a new signing seed, a Live API key, and a first anchor against Live. See Go live.

​

One key, one agent name, forever

A signing public key is unique across all of Sanning, not only your organization, and stays that way in any state, forever. Two rules follow from that, and both SDK enrollment and the console’s re-key enforce them:

• A key already enrolled under another name is refused. Registering it again under a different name would let one key sign for two identities. This is SIGNING_KEY_ALREADY_ENROLLED (409): for another name in your own organization, when the key is active or retired there; for a name in a different organization, whatever state the key is in there, including revoked. A key revoked under a name in your own organization gets the more specific refusal below instead. The error names no other organization.
• A revoked key is refused everywhere, permanently. Revocation repudiates the key itself, not only the name that held it, so no name, in any organization, may register it again. Inside your own organization the refusal is SIGNING_KEY_PREVIOUSLY_REVOKED (409); a key revoked in another organization is refused as SIGNING_KEY_ALREADY_ENROLLED (409), because a refusal that reaches across organizations says nothing about the state a key is in somewhere you cannot see. A key stays reserved even if the organization that enrolled it is later deleted.

Replicas of one agent share its name and key. Use a distinct key for every agent you run, anywhere: a key one deployment already holds cannot enroll under a second name or a second organization, and cannot come back after it is revoked.

​

Nothing in the console enrolls a key

Settings, Signing keys lists every key enrolled to sign an agent’s envelopes, but it has no Create action. A key’s row exists because an agent anchored with it, not because someone added it.

​

Revoke an active key

An owner or admin opens Settings, Signing keys, finds the active key, and selects Revoke. Revocation is scoped to your organization: it stops that key from anchoring anything further for your organization, and it cannot be undone by re-enrolling the same key, including by whoever holds it. Records the key signed before revocation are untouched and still verify.

​

Re-key a revoked name

A revoked name does not disappear and cannot enroll through the SDK again, so recovering it takes both a console step and a runtime one.

1. Generate a new key pair where the agent runs, using the same tool you used the first time (openssl rand -hex 32 produces a seed; derive the public half from it).
2. In Settings, Signing keys, an owner or admin selects Re-key on the revoked name and pins that public key. This step only reserves the key: it does not yet let the name anchor.
3. Restart the agent with the new seed. On its first anchor, the SDK’s enrollment proves possession of the pinned key to the control plane, which completes the re-key and lets the name anchor again.

The public half is all the console ever needs. Sanning never sees the seed that produced it, before or after a re-key. A pin that is never claimed can be cancelled from the same Settings, Signing keys screen. Re-key refuses a name that is not revoked (SIGNING_KEY_NOT_REVOKED, 409): a live key rotates through the SDK instead, with the outgoing key’s counter-signature. See Errors for both codes.

​

What to read next