Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

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.

FieldWhat it is
kindperson, service, or process (a business process run by the kernel)
accountIdthe account, for persons; at most one identity per account and tenant
profiledisplayName, title, email: personal data, in the vault under identity:<id>
membershipsthe groups it belongs to: each with an ID, the group, a scope and an optional expiry, active or suspended
apiKeysservices and processes only: the hashes of their keys, with label, expiry and whether revoked
statusactive, 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:

ScopeMeans
nonethe 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:

  1. KitApi.createApiKey(...) generates the key, sends CreateApiKey with it, and returns it once: key_<keyId>_<secret>. Only its hash is stored.
  2. 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.
  3. RevokeApiKey ends 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 (DeleteIdentity on 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 ​

AggregateUnique keysFacts
identity.identityaccount, processactive

Commands ​

Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.

CommandFieldsWritesWho may send itRefused with
CreateApiKey
on identity
keyId: string
secret: string (secret)
label?: string
expiresAt?: number | null
ApiKeyCreateda group permissionexists, invalid_key, invalid_state, not_a_service
CreateServiceIdentity
on identity
displayName: string (personal)IdentityCreateda group permissionexists, invalid_name
CreateProcessIdentity
on identity
process: stringIdentityCreatedonly the kit's reactorsexists, invalid_process
CreateIdentity
on identity
accountId: string
displayName?: string (personal)
title?: string (personal)
email?: string (personal)
IdentityCreatedonly the kit's reactorsexists, invalid_account
DeleteIdentity
on identity
—IdentityDeleteda group permission, or the sender itselfnot_found; requires: no tenancy.tenant holds it as owner
GrantMembership
on identity
membershipId: string
group: string
scope?: Scope | null
expiresAt?: number | null
MembershipGranteda group permission; only with permissions the sender holdsexists, invalid_membership, invalid_scope, invalid_state; requires: group.group is active
ReactivateIdentity
on identity
—IdentityReactivateda group permissioninvalid_state
ResumeMembership
on identity
membershipId: stringMembershipResumeda group permissionnot_found
RevokeApiKey
on identity
keyId: stringApiKeyRevokeda group permissionnot_found
RevokeMembership
on identity
membershipId: stringMembershipRevokeda group permissionnot_found
SuspendMembership
on identity
membershipId: stringMembershipSuspendeda group permissionnot_found
SuspendIdentity
on identity
reason?: stringIdentitySuspendeda group permissioninvalid_state
UpdateProfile
on identity
displayName?: string (personal)
title?: string (personal)
email?: string (personal)
ProfileUpdateda group permission, or the sender itselfinvalid_state

Events ​

EventFieldsVaultNote
IdentityCreatedkind: IdentityKind
accountId: string | null
displayName: string | null
title: string | null
email: string | null
displayName, title, email under identity:<id>—
ProfileUpdateddisplayName: string | null
title: string | null
email: string | null
displayName, title, email under identity:<id>—
MembershipGrantedmembershipId: string
group: string
scope: Scope | null
expiresAt: number | null
——
MembershipSuspendedmembershipId: string——
MembershipResumedmembershipId: string——
MembershipRevokedmembershipId: string——
ApiKeyCreatedkeyId: string
hash: string
label: string
expiresAt: number | null
——
ApiKeyRevokedkeyId: string——
IdentitySuspendedreason: 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.

QueryFieldsAboutAnswerWho may ask
FindIdentityByAccount
by identity.identities
accountId: string—{ identityId: string; status: IdentityStatus }the API (its api group)
GetIdentity
by identity.identities
identityId: stringidentity.identity in identityIdIdentityRow { id, tenant, kind, accountId, displayName, status, memberships, apiKeys }a group permission, or the sender itself
ListMyIdentities
by identity.identities
accountId: stringaccount.account in accountId{ tenant: string; identityId: string; status: IdentityStatus }[]any signed-in account, or the sender itself
ListIdentities
by identity.identities
——IdentityRow[]a group permission
FindApiKey
by identity.identities
keyId: string—{ tenant: string; identityId: string; hash: string; expiresAt: number | null; revoked: boolean }the API (its api group)

Listeners ​

ListenerOnSubmits
identity.identities (read model, order -20)IdentityCreated, ProfileUpdated, MembershipGranted, MembershipSuspended, MembershipResumed, MembershipRevoked, ApiKeyCreated, ApiKeyRevoked, IdentitySuspended, IdentityReactivated, IdentityDeleted, TenantDeleted—
identity.owners (reactor, order -10)TenantCreatedCreateIdentity, AddOwner
identity.invitations (reactor, order -10)InvitationAcceptedside effects only
identity.invitations (reactor, order -10)InvitationLinkUsedside effects only
identity.cleanup (reactor, order -25)TenantDeletedDeleteIdentity
identity.follow (reactor, order -10)AccountDeletedDeleteIdentity
identity.follow (reactor, order -10)GroupDeletedRevokeMembership