ApiKey
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
| Field | Type | Description |
|---|---|---|
accountId | string | null | Owning account ID (null for system keys) |
accountName | string | null | Owning account name (null for system keys) |
createdAt | number | Creation timestamp in epoch seconds |
domains | string[] | 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. |
id | string | Unique API key identifier |
idleExpiresAt | number | null | The 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. |
idleTtlS | number | null | Seconds 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. |
kind | string | null | What 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. |
lastUsedAt | number | null | Approximately 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. |
managed | boolean | True if this key is managed by platform infrastructure |
name | string | Descriptive name for the API key |
requireActing | boolean | System 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. |
requireActingCredential | boolean | System 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. |
revokedAt | number | null | Timestamp when key was revoked in epoch seconds, or null |
role | string | Key role ('system' or 'account') |
Used by
| Method | What it does |
|---|---|
apiKeys.list | List API keys |