Identity

Every statement names who acted. In an immutable ledger you cannot fix identity later, so the decisions on this page are worth making before your first production statement, not after your millionth.

The actor shape

Actors in Empress use xAPI account objects: a stable name plus a homePage that says which system minted it. The pair is the identity — the same name under a different homePage is a different actor.

"actor": {
  "account": {
    "name": "agent-7",
    "homePage": "https://empress.eco"
  }
}

One canonical ID, forever

Pick one canonical identifier per actor and never change it. Everything Empress derives — belief state, actor stats, percentiles, cross-session history — keys on the actor. An actor whose ID changes mid-history looks to the substrate like two strangers, each with half a record. The best canonical ID is an opaque string your own platform mints and controls: it survives auth-provider migrations, email changes, and company renames without a ripple.

Anonymous and device actors

Not every actor is a signed-in user. Anonymous sessions and devices get their own stable IDs — a session or device identifier used consistently as the account name. When an anonymous actor later becomes a known one, do not rewrite history and do not re-emit old statements under the new ID. Instead keep an alias map on your side — this device ID and that canonical ID are the same actor — and read the union: query both IDs and merge. The ledger stays honest about what was known at the time; your application layer holds the linkage.

What never goes in a statement

Never put emails in statements, and never put auth-provider user IDs in statements. Emails are personal data that people expect to change and expect to be forgotten — neither is possible in an immutable ledger. Auth-provider IDs weld your behavioral history to a vendor: migrate providers and every actor’s past is stranded under an ID that no longer exists anywhere. The statement carries your opaque canonical ID; the mapping from that ID to a person lives in your own systems, where it can be updated or deleted.

Why drift compounds

In a mutable database, an identity mistake is a migration. In an immutable ledger, it is permanent: every statement emitted under a wrong or unstable ID stays that way, and every derived truth computed from those statements inherits the split. A month of drift means a month of belief state, stats, and history attributed to an actor who never quite existed. The cost of choosing IDs carefully is an afternoon; the cost of not doing so grows with every statement you emit.

---

Next: Concepts · Tenant integration · API reference