Skip to Content
GET
/api/v1/auth/whoami

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 unless you use it' rather than letting the holder discover it as a 401.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Response Body

Identity and permission scope of the calling token

application/json
  1. response
accountId*|

Owning account ID, or null for system keys

credentialId*|

Credential ULID for mailbox app passwords, or null

domains?array<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).

idleExpiresAt*|

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.

Formatint64
keyId*|

API key ID for system or account bearers, or null for mailbox app passwords

kind*|

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*|

Mailbox ULID for mailbox app passwords, or null

permittedRecipients?array<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

scope*|||

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

type*string

Bearer credential permission scope

Value in"system""account""mailbox"
Example Request
curl -X GET 'https://api.open.email/api/v1/auth/whoami'
Example Response
{
  "accountId": "01J9ACCT8B1D4F7H2K00000000",
  "credentialId": null,
  "idleExpiresAt": 1803859200,
  "keyId": "01J9KEYX5C8E2G5J9M00000000",
  "kind": "cli",
  "mailboxId": null,
  "scope": null,
  "type": "account"
}