Skip to Content

The WhoamiResult type of the TypeScript SDK, which auth.whoami take or answer.

type WhoamiResult = {
  accountId: string | null
  credentialId: string | null
  domains?: string[]
  idleExpiresAt: number | null
  keyId: string | null
  kind: string | null
  mailboxId: string | null
  permittedRecipients?: string[]
  scope: ('read' | 'write' | 'send' | 'full') | null
  type: ('system' | 'account' | 'mailbox')
}

Fields

FieldTypeDescription
accountIdstring | nullOwning account ID, or null for system keys
credentialIdstring | nullCredential ULID for mailbox app passwords, or null
domainsstring[]Optional. An account key's domain scope (migration 0078), sorted — ABSENT for an unscoped key and for every other credential kind. Present, this key reaches only these domains' directory and the mailboxes with an address on them; a call outside that answers 404 (a resource) or 403 account_credentials_required (the account tier, and JMAP).
idleExpiresAtnumber | nullThe idle deadline computed from the key's recorded last use (or creation if no use is recorded), in epoch seconds, or null when it never lapses. Usage updates are best-effort and coalesced with a five-minute interval, so successful use may not immediately advance this deadline. This response can precede its own request's renewal.
keyIdstring | nullAPI key ID for system or account bearers, or null for mailbox app passwords
kindstring | nullWhat this key is ('cli' for one the browser login minted), or null — including for every mailbox app password, which has no key row. Display metadata; nothing authorizes on it.
mailboxIdstring | nullMailbox ULID for mailbox app passwords, or null
permittedRecipientsstring[]Optional. A mailbox credential's OWN outbound recipient allowlist (design D50) — exact addresses and *@domain wildcards, INTERSECTED with the identity's at every submission site, so this list is a bound and not a promise that everything in it is deliverable. ABSENT when this credential carries no list of its own (the domains convention), which is not the same fact as []: an empty array is a credential permitted to send to NOBODY. Here so an agent door learns its correspondents up front instead of discovering them as a per-recipient recipient_not_permitted
scope('read' | 'write' | 'send' | 'full') | nullA mailbox credential's scope — 'read', 'write', 'send' or 'full' — or null for an API key. What this bearer may do of what its mailbox may do; a call outside it answers 403 credential_scope naming the rung it needs
type('system' | 'account' | 'mailbox')Bearer credential permission scope

Used by

MethodWhat it does
auth.whoamiGet current authenticated identity

On this page