# Get current authenticated identity

Answers what the presented bearer credential IS and therefore what it reaches; call it first when integrating. Key on `type`: `account` (an `oek_…` API key: the account's directory plus every mailbox it owns), `mailbox` (an `oemp_…` app password: one mailbox, `mailboxId` says which; directory routes answer 403 insufficient_scope), or `system` (an operator key). `scope` and `permittedRecipients` are a mailbox credential's own bound (D50): what it may do, and who it may send to — asked once here rather than learned from a 403 per call. `idleExpiresAt` warns when a key will lapse from disuse, so a client can say 'this key stops working on <date> unless you use it' rather than letting the holder discover it as a 401.

## `GET /api/v1/auth/whoami`

### Responses

**200** — Identity and permission scope of the calling token

`application/json` → WhoamiResult

- `accountId` (string | null, required) — Owning account ID, or null for system keys
- `credentialId` (string | null, required) — Credential ULID for mailbox app passwords, or null
- `idleExpiresAt` (integer | null, required) — The 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.
- `keyId` (string | null, required) — API key ID for system or account bearers, or null for mailbox app passwords
- `kind` (string | null, required) — What 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.
- `mailboxId` (string | null, required) — Mailbox ULID for mailbox app passwords, or null
- `scope` ("read" | "write" | "send" | "full" | null, required) — A 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
  - _option 1: "read" | "write" | "send" | "full"_
  - _option 2: null_
  - _option 3: null_
- `type` ("system" | "account" | "mailbox", required) — Bearer credential permission scope
- `domains` (string[]) — 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).
- `permittedRecipients` (string[]) — 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`

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/auth/whoami' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.auth.whoami`](/docs/sdks/typescript/auth/whoami)

```ts
const whoamiResult = await openemail.auth.whoami()
```
