Skip to Content

The ApiKey type of the TypeScript SDK, which apiKeys.list take or answer.

type ApiKey = {
  accountId: string | null
  accountName: string | null
  createdAt: number
  domains?: string[]
  id: string
  idleExpiresAt: number | null
  idleTtlS: number | null
  kind: string | null
  lastUsedAt: number | null
  managed: boolean
  name: string
  requireActing: boolean
  requireActingCredential: boolean
  revokedAt: number | null
  role: string
}

Fields

FieldTypeDescription
accountIdstring | nullOwning account ID (null for system keys)
accountNamestring | nullOwning account name (null for system keys)
createdAtnumberCreation timestamp in epoch seconds
domainsstring[]Optional. The domains this key is scoped to (migration 0078), sorted; ABSENT for a key with full account authority. A scoped key reaches only these domains' directory and the mailboxes with an address on them; everything account-level answers 403 account_credentials_required. An EMPTY list is a stored scope core cannot read (a hand-edited row): that key refuses to authenticate, and this is where the listing says so — never folded into absent, which would show a dead key as the widest one.
idstringUnique API key identifier
idleExpiresAtnumber | nullThe idle deadline computed from idleTtlS and the recorded lastUsedAt/createdAt, in epoch seconds, or null when the key never lapses. A successful renewal moves this deadline. During an account's deletion window, a key that was live at deletion can still access the restricted account recovery routes after this timestamp.
idleTtlSnumber | nullSeconds of disuse after which this key stops authenticating (migration 0051), or null for a key that never lapses. Measured from lastUsedAt, or from createdAt while no use has been recorded. Usage updates are best-effort and coalesced with a five-minute interval; this is not an end-to-end precision guarantee, and a key can lapse before idleTtlS has passed since its final successful request.
kindstring | nullWhat this key is ('cli' for one the browser login minted), or null. Display metadata only — the caller sets it at mint, so nothing authorizes on it; it lets a keys list identify a row without matching on a name the owner can change.
lastUsedAtnumber | nullApproximately when this key last authenticated at core, in epoch seconds, or null if no use has been recorded. A best-effort update is attempted on first use, then coalesced with a five-minute interval. Delayed or failed writes can leave this older than the last successful request; for a key with idleTtlS, idle expiry is measured from this recorded value.
managedbooleanTrue if this key is managed by platform infrastructure
namestringDescriptive name for the API key
requireActingbooleanSystem keys only (migration 0046): when true, mailbox-scoped requests made with this key must declare X-Acting-Identity or are refused 403 acting_required. Set it on an INGRESS credential (a gateway or BFF acting for a logged-in user); never on an autonomous one (smtp-in, pop3-fetch, automation), which has no acting user.
requireActingCredentialbooleanSystem keys only (migration 0081): when true, those same requests must ALSO declare X-Acting-Credential, naming the mailbox credential the call acts under, or are refused 403 acting_credential_required — so the credential's scope and recipient list survive being relayed under this key. It is also what lets /auth/verify hand this key a credential scoped below 'full': only a key that carries the header can honour a scope, and a session it would silently exceed must not open.
revokedAtnumber | nullTimestamp when key was revoked in epoch seconds, or null
rolestringKey role ('system' or 'account')

Used by

MethodWhat it does
apiKeys.listList API keys

On this page