# ApiKey

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

```ts
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`](/docs/sdks/typescript/api-keys/list) | List API keys |
