IdentityClient
The IdentityClient type of the TypeScript SDK, which identities.listClients take or answer.
type IdentityClient = {
accountId: string | null
asOrg: string | null
asn: number | null
city: string | null
client: string | null
country: string | null
credentialActive: boolean | null
credentialId: string | null
credentialKind: string | null
credentialName: string | null
facets: ('mail' | 'pim')[]
firstSeenAt: number
id: string
identityId: string
ip: string
lastSeenAt: number
notifiedAt: number | null
protocol: ('imap' | 'pop3' | 'sieve' | 'smtp' | 'caldav' | 'carddav' | 'dav' | 'jmap' | 'webmail' | 'api')
touchCount: number
}Fields
| Field | Type | Description |
|---|---|---|
accountId | string | null | The identity's account at first sighting, or null |
asOrg | string | null | Autonomous system organisation, or null (same rule) |
asn | number | null | Autonomous system number, or null (same rule) |
city | string | null | City, or null (same rule as country) |
client | string | null | The client's self-description (User-Agent, IMAP ID) as last seen, or null |
country | string | null | ISO 3166-1 alpha-2 country, or null when NOBODY LOOKED — never 'unknown'. Mail-protocol rows carry null until the fleet resolves locations |
credentialActive | boolean | null | Whether the credential would still be accepted now: true while it exists, is not revoked and is not past its expiry; false once revoked, expired or purged; null when unattributed. Each webmail sign-in mints its own credential, so a webmail row whose value is false is a session that has ended |
credentialId | string | null | The credential the client presented — the thing to revoke — or null when the reporting surface could not attribute one. Never render null as 'your password' |
credentialKind | string | null | password (the identity's own password) or app_password; null when unattributed or purged |
credentialName | string | null | The credential's label as its owner gave it ("old-phone"; webmail names its sessions "webmail session"), so a reader can say which app password to revoke without a lookup per row. null when unattributed, unnamed, or purged; a revoked credential keeps its name |
facets | ('mail' | 'pim')[] | What the client TOUCHED — mail, pim (calendars, contacts, tasks) or both — never what the identity owns. A JMAP client that read a mailbox and a calendar carries both |
firstSeenAt | number | First sighting, epoch seconds |
id | string | Client row ULID — the FIRST sighting's; not the sort key |
identityId | string | The identity this client reached |
ip | string | The client's address as LAST seen, canonical (RFC 5952 for v6). An IPv6 client is one row per /64: the address here is the most recent host within it |
lastSeenAt | number | Last sighting, epoch seconds — coalesced hourly, so exact for a first sighting and up to one hour stale after it. 'Connected now' is a presentation rule over this, not a fact the row asserts |
notifiedAt | number | null | When this client was flagged as a NEW LOCATION — a network or (country, network operator) the identity had not been reached from before — and the notice raised: mail to the identity's inbox and verified recovery address (unless the identity's prefs carry notifyNewClient: false) and an identity.client.new event. null for the first client an identity ever had, for a known network or location, and past the daily cap |
protocol | ('imap' | 'pop3' | 'sieve' | 'smtp' | 'caldav' | 'carddav' | 'dav' | 'jmap' | 'webmail' | 'api') | How the client reached the platform. dav is a CalDAV/CardDAV request on neither half (a principal PROPFIND); api is the REST surface; webmail is a browser session reported by the webmail frontend |
touchCount | number | How many coalesced sightings were recorded, not how many connections were made |
Used by
| Method | What it does |
|---|---|
identities.listClients | List an identity's clients |