Tutorial 1 · foundation

Create and sign with an ENTITY identity

The goal is to create a persistent ent2- Entity, verify that its manifest is cryptographically valid, then produce a signed payload record without treating an application account or device as the sovereign root.

Before you start

Use the current ENTITY checkout and its Python environment.
Choose a protected local state directory.
Do not publish private key material. The identity vault writes operational and recovery private keys beneath its state directory.

1. Create the identity

The canonical identity class is EntityIdentityVault. Instantiate the vault with a state directory, then call create(display_name, entity_type, aliases, metadata).

vault = EntityIdentityVault(r"E:\ENTITY_TUTORIAL_STATE")
manifest = vault.create(
    display_name="Tutorial Organization",
    entity_type="organization",
    aliases=["tutorial-org"],
    metadata={"purpose": "ENTITY tutorial"},
)
entity_id = manifest["entity_id"]
print(entity_id)

A new identity is an ent2- identifier. Supported public types include person, family, business, product, application, system, community, service, organization and project.

Checkpoint: keep the returned entity_id. The manifest should contain separate active operational signing and recovery verification methods.

2. Verify the manifest

assert EntityIdentityVault.verify_manifest(manifest)
print("MANIFEST_VERIFIED")

Verification checks the manifest schema, Entity ID syntax, active verification method, signature suite and signature. Where rotation/recovery proofs exist, continuity must also verify.

3. Sign a governed payload

payload = {
    "action": "TUTORIAL_ASSERTION",
    "subject": "example-object",
    "statement": "This payload was signed by the tutorial Entity"
}
record = vault.sign(entity_id, payload)
print(record)

The resulting signature record binds the Entity ID, active key ID, signature suite, signing time and SHA-256 of the canonical payload.

4. Inspect what was actually proven

Result	Meaning
Valid manifest	The public identity document and its cryptographic continuity verify.
Valid signature record	The active Entity key signed the canonical record for that payload hash.
Not proven	Legal ownership, truth of the payload, payment, or permission outside the authority actually represented by the Entity.

5. Understand operational vs recovery keys

The reference identity creates separate Ed25519 roles. The operational key is used for assertion/authentication/contract signing. The recovery key exists to authorize continuity when an operational signing key must be recovered.

Use rotate_signing_key() for ordinary key rotation and recover_signing_key() for recovery. Both preserve manifest continuity rather than silently replacing identity history.

Critical boundary: do not copy the private key directory into public evidence, a Git repository or a tutorial screenshot. Back up sensitive identity state using the operator backup procedures.

6. Success criteria

You have one ent2- ID.
verify_manifest() returns true.
You can sign a payload using the active operational key.
You understand that the Entity—not the host, app account or device—is the authority root.

Tutorial 2: BTDU ingest →Identity reference