Identity

Create, manage, and remove identities. Import and export contacts. Manage signers and the contact request flow.

For reading identities (list, get, sign, verify), see the App API — those endpoints are available to all apps.

Identity lifecycle

identity.create (name: string): { uid, data, signed }

Create a new identity. Returns the genesis document CBOR for ds.inject(). The identity signal fires on success.

const result = await app.request('identity.create', ['Alice']);
// { uid: Buffer, data: Buffer, signed: [...] }

identity.update (uid: Uid, { name?, hosts? }): { success }

Update identity metadata or host list.

await app.request('identity.update', [uid, { name: 'New Name' }]);

identity.remove (uid: Uid): bool

Remove an identity and close all its connections. Destroys private keys permanently.

identity.export (uid: Uid): Document

Export identity as a shareable document. Used for contact exchange.

Signers

Signers are Ed25519 keypairs within an identity. An identity can have multiple signers — typically one per device.

identity.signer.create (uid: Uid, name?: string): { signerId, pubkey }

Create a new signer for an existing identity.

identity.signer.add (uid: Uid, pubkey: Buffer(32), name?: string): { added }

Add a remote signer (no private key) to an identity. Used when a new device joins. Idempotent.

identity.signer.remove (uid: Uid, signerId: Uid): bool

Remove a signer from an identity. The signer's keys are destroyed.

Contacts

identity.contact.import (document: Document): Contact

Import a contact from exported identity data.

identity.contact.add (luid: Uid, ruid: Uid): bool

Directly add a contact, bypassing the contact request flow.

Contact requests

The standard flow for establishing a contact relationship between two identities.

identity.contact.request.send (luid: Uid, contact: Contact): bool

Send a contact request to another identity.

identity.contact.request.list (void): ContactRequest[]

List pending incoming contact requests. The identity signal fires when new requests arrive.

identity.contact.request.accept (luid: Uid, ruid: Uid): bool

Accept a contact request.

identity.contact.request.decline (luid: Uid, ruid: Uid): bool

Decline a contact request.

Join mode

Allows additional signers to join an existing identity — used when adding a new device.

identity.join.enable (uid: Uid): void

Enable join mode. Other signers can request to join this identity.

identity.join.disable (uid: Uid): void

Disable join mode.