Appearance
Identities
An identity is someone inside one tenant: a person (through their account) or a service, such as another program that calls your API. Permissions, profiles and group memberships belong to identities, so the same person can own one tenant and be a guest in another, with a different display name in each.
One aggregate, identity.identity, with a random ID, under its tenant.
| Field | What it is |
|---|---|
kind | person, service, or process (a business process run by the kernel) |
accountId | the account, for persons; at most one identity per account and tenant |
profile | displayName, title, email: personal data, in the vault under identity:<id> |
memberships | the groups it belongs to: each with an ID, the group, a scope and an optional expiry, active or suspended |
apiKeys | services and processes only: the hashes of their keys, with label, expiry and whether revoked |
status | active, suspended or deleted |
How identities come to be
You rarely create a person's identity yourself; the kit's reactors do it:
- Invitation accepted: the person gets an identity in the tenant (or keeps theirs) with the invitation's groups, and becomes an owner for an owner invitation.
- Self-service tenant: its creator gets an identity in it and becomes its owner.
Services are created with CreateServiceIdentity by anyone whose group allows it.
Memberships
GrantMembership puts an identity in a group:
| Scope | Means |
|---|---|
| none | the group's permissions apply in the whole tenant |
{ type: "shop.order", id: "o-17" } | they apply only to that one aggregate, like a relation set by hand |
A membership can expire (expiresAt): it stops counting at that moment, with no command needed. It can be suspended and resumed without losing it, or revoked. When a group is deleted its memberships stop counting at once, and a reactor revokes them afterwards.
Nobody grants a group whose permissions they do not hold themselves (see no escalation).
API keys
A service identity signs its requests with an API key instead of a session:
KitApi.createApiKey(...)generates the key, sendsCreateApiKeywith it, and returns it once:key_<keyId>_<secret>. Only its hash is stored.- A request carries the key; your API calls
KitApi.checkApiKey(key), which compares the hash and returns the request context to submit with (the key's identity and tenant). The answer is cached for a minute. RevokeApiKeyends it. The middleware learns of it from the event and refuses the key at once, cache or not.
Every command sent with a key carries the key's ID in senderSession, so the log shows each use; there is no separate event per use.
Processes
A business process the kernel runs sends commands like a service does, so it needs an identity too. The kit creates one for each process on its first registration: in the platform tenant, kind process, named after the process (shop.fulfilment), with an API key, and tells the kernel to act as that identity.
The new identity holds no permissions. A platform administrator grants it a group of the platform tenant with exactly what the process sends (shop.Confirm, shop.Ship, shop.Cancel); platform groups hold in every tenant. Until then its commands are refused and its cases stop as incidents, which kernable processes retry resumes once the group is granted. Revoking the process's API key stops the process at once, without a deploy. A later deploy does not give it a new key: resuming it is a deliberate step (a new key, then processAct with it).
Leaving and deleting
- An identity may leave its tenant itself (
DeleteIdentityon its own identity). - Others with the permission suspend, reactivate and delete identities.
- An identity that owns its tenant cannot be deleted until it is removed as owner; the kernel checks this atomically.
- Deleting erases the profile from the vault. When a tenant or an account is deleted, the kit's reactors delete the identities concerned.
Reference
Types
The types the tables below name, from identity/domain.ts:
ts
type IdentityKind = "person" | "service" | "process";
type IdentityStatus = "none" | "active" | "suspended" | "deleted";
interface Scope { type: string; id: string }
interface Membership {
membershipId: string;
group: string;
scope: Scope | null;
expiresAt: number | null;
status: "active" | "suspended";
}
interface ApiKey { keyId: string; hash: string; label: string; expiresAt: number | null; revoked: boolean }Aggregates
| Aggregate | Unique keys | Facts |
|---|---|---|
identity.identity | account, process | active |
Commands
Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.
| Command | Fields | Writes | Who may send it | Refused with |
|---|---|---|---|---|
CreateApiKeyon identity | keyId: stringsecret: string (secret)label?: stringexpiresAt?: number | null | ApiKeyCreated | a group permission | exists, invalid_key, invalid_state, not_a_service |
CreateServiceIdentityon identity | displayName: string (personal) | IdentityCreated | a group permission | exists, invalid_name |
CreateProcessIdentityon identity | process: string | IdentityCreated | only the kit's reactors | exists, invalid_process |
CreateIdentityon identity | accountId: stringdisplayName?: string (personal)title?: string (personal)email?: string (personal) | IdentityCreated | only the kit's reactors | exists, invalid_account |
DeleteIdentityon identity | — | IdentityDeleted | a group permission, or the sender itself | not_found; requires: no tenancy.tenant holds it as owner |
GrantMembershipon identity | membershipId: stringgroup: stringscope?: Scope | nullexpiresAt?: number | null | MembershipGranted | a group permission; only with permissions the sender holds | exists, invalid_membership, invalid_scope, invalid_state; requires: group.group is active |
ReactivateIdentityon identity | — | IdentityReactivated | a group permission | invalid_state |
ResumeMembershipon identity | membershipId: string | MembershipResumed | a group permission | not_found |
RevokeApiKeyon identity | keyId: string | ApiKeyRevoked | a group permission | not_found |
RevokeMembershipon identity | membershipId: string | MembershipRevoked | a group permission | not_found |
SuspendMembershipon identity | membershipId: string | MembershipSuspended | a group permission | not_found |
SuspendIdentityon identity | reason?: string | IdentitySuspended | a group permission | invalid_state |
UpdateProfileon identity | displayName?: string (personal)title?: string (personal)email?: string (personal) | ProfileUpdated | a group permission, or the sender itself | invalid_state |
Events
| Event | Fields | Vault | Note |
|---|---|---|---|
IdentityCreated | kind: IdentityKindaccountId: string | nulldisplayName: string | nulltitle: string | nullemail: string | null | displayName, title, email under identity:<id> | — |
ProfileUpdated | displayName: string | nulltitle: string | nullemail: string | null | displayName, title, email under identity:<id> | — |
MembershipGranted | membershipId: stringgroup: stringscope: Scope | nullexpiresAt: number | null | — | — |
MembershipSuspended | membershipId: string | — | — |
MembershipResumed | membershipId: string | — | — |
MembershipRevoked | membershipId: string | — | — |
ApiKeyCreated | keyId: stringhash: stringlabel: stringexpiresAt: number | null | — | — |
ApiKeyRevoked | keyId: string | — | — |
IdentitySuspended | reason: string | — | — |
IdentityReactivated | — | — | — |
IdentityDeleted | — | erases identity:<id> | Erases the identity's personal data. |
Queries
A query about one aggregate names it (static target): the middleware decides on that aggregate as on a command's.
| Query | Fields | About | Answer | Who may ask |
|---|---|---|---|---|
FindIdentityByAccountby identity.identities | accountId: string | — | { identityId: string; status: IdentityStatus } | the API (its api group) |
GetIdentityby identity.identities | identityId: string | identity.identity in identityId | IdentityRow { id, tenant, kind, accountId, displayName, status, memberships, apiKeys } | a group permission, or the sender itself |
ListMyIdentitiesby identity.identities | accountId: string | account.account in accountId | { tenant: string; identityId: string; status: IdentityStatus }[] | any signed-in account, or the sender itself |
ListIdentitiesby identity.identities | — | — | IdentityRow[] | a group permission |
FindApiKeyby identity.identities | keyId: string | — | { tenant: string; identityId: string; hash: string; expiresAt: number | null; revoked: boolean } | the API (its api group) |
Listeners
| Listener | On | Submits |
|---|---|---|
identity.identities (read model, order -20) | IdentityCreated, ProfileUpdated, MembershipGranted, MembershipSuspended, MembershipResumed, MembershipRevoked, ApiKeyCreated, ApiKeyRevoked, IdentitySuspended, IdentityReactivated, IdentityDeleted, TenantDeleted | — |
identity.owners (reactor, order -10) | TenantCreated | CreateIdentity, AddOwner |
identity.invitations (reactor, order -10) | InvitationAccepted | side effects only |
identity.invitations (reactor, order -10) | InvitationLinkUsed | side effects only |
identity.cleanup (reactor, order -25) | TenantDeleted | DeleteIdentity |
identity.follow (reactor, order -10) | AccountDeleted | DeleteIdentity |
identity.follow (reactor, order -10) | GroupDeleted | RevokeMembership |
