nextmail me

Returns what the key is: its id, whether it is a live or test key, the workspace it belongs to, the scopes it can use and the allowlists that narrow who it may send as. It needs no scope, because a key may always describe itself, so it works with any valid key and is the first call to make when a request is refused.

scopes is the effective list and the only one that authorises anything. It is the scopes the key was created with intersected with the permissions of the role it was issued under, resolved on every request rather than frozen into the key. grantedScopes is what the key was created holding and roleId names the role that capped it, so a scope present in grantedScopes and missing from scopes was removed by that role. A 403 insufficient_scope on a key the console shows as holding the scope is almost always this, and the fix is to change the role rather than to mint another key.

A key can be narrowed by whole domains, by individual addresses, or by both. domainAllowlist holds whole domains, and the key may send as any address on one of them, including addresses created after the key was. addressAllowlist holds individual addresses and covers only those. Both null means the key may send as any address the workspace owns. When either is set the key is narrowed, and reads of sent mail, tracking and calendar narrow to the same set. An address whose domain is already in domainAllowlist is dropped from addressAllowlist when the key is saved, so the two lists never overlap.

Called with an OAuth access token it describes the token instead, and object tells the two apart. A key answers object: 'api_key' and kind: 'apiKey'. A token answers object: 'oauth_token' and kind: 'oauth', with id null, clientId naming the connected app, roleId null and mode always live. scopes and grantedScopes are the permissions the person approved for the app, and the allowlists are the addresses and domains the app may reach. expiresAt is when that approval runs out, or null when it never does. It is not the expiry of the access token, which the app renews with its refresh token.

An authentication smoke test. It runs the same key check every other endpoint runs and answers ok: true with the key id, its mode, the workspace and the effective scopes. It needs no scope, so a key with none at all still gets a 200.

Use it in a health check or at process start to fail fast on a revoked, expired or mistyped key. The answer carries the same scope detail as me.get, scopes effective and grantedScopes as created with roleId naming the cap between them, but it leaves out both allowlists. Call me.get when you need to know which domains and which addresses the key may send as.

An OAuth access token gets the same answer with kind: 'oauth', keyId null, clientId naming the connected app, roleId null and mode always live. A key answers kind: 'apiKey'.

Mints a new secret for the key making the call and resolves with the same body as me.get plus token, the new key in full. That is the only place the value appears, so store it before anything else.

Everything else about the key survives. The id, the mode, the scopes, the role ceiling, the address allowlist and the domain allowlist all come back unchanged, so token is the only thing your configuration has to change. Because the id is stable, an audit trail joined on it stays joined up across rotations.

There is no overlap window. The old secret stops authenticating the moment this call commits, and neither secret can be shown again. Write token to wherever the key is read from before the next request. A lost response is the bad case: the rotation may have committed to a secret nobody saw, which leaves the key unusable until someone mints it a new secret in the console.

Returns one page of the calls the key making the request made, newest first. It needs no scope: a key may always read its own log, and it reads no other key's here. keys.listRequests and keys.listWorkspaceRequests are the ones that reach other keys, behind keys:read.

The request log records every authenticated call the key made: method, path, status, error code, duration, IP and user agent, and never a body or a query string. Nothing is pruned, so the log reaches back to the key's first call, and it runs straight through a rotation because it hangs off the key id. --failed-only, statuses, path, since and until narrow it, and they combine.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns one page of the audit log of the key making the request, newest first. It needs no scope, and it reads no other key's history: keys.listActivity and keys.listWorkspaceActivity do that, behind keys:read.

Every change to the key is a row: created, updated, rotated, deactivated and reactivated, plus auth_failed for every call that presented the key and was refused. actor names who made the change, a person as @username or a key as API key <name> in label, and detail.source says where it came from: console, api, mcp or documentation.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns the figures of the key making the request: the requests it made and how many failed, the calls refused because its secret was wrong, revoked or expired, the routes it called most with the median time each took, and the status codes it got back. It needs no scope, and it reads no other key's figures: keys.stats does that.

sends, the mail the key sent and what became of it, is filled only when the key holds emails:read. Without that scope it is null, never zeros, so a missing permission cannot read as a quiet week.

The window runs from since to until, and left out it is the 30 days before now. grain sets the bucket width of the series and --offset-minutes shifts the boundaries so days break where the reader's day does.