Account

The answer to an unexplained 403 or 409. unrestricted is true only on a key with neither allowlist set, and it means any local-part on a verified domain is accepted, including ones nobody has created. A key holding whole domains reads as unrestricted: false and still takes any local-part on those domains, so GET /keys/self is where you read which ones. canSend on an address is false when the address is disabled, when neither allowlist on the key covers it, or when the domain cannot sign yet, and sendingVerified on each domain is that last fact on its own.

Requires the emails:send scope.

Needs no scope: a key may always describe itself.

scopes is the EFFECTIVE list and the only one that authorises anything: the scopes on the key itself, intersected with the permissions of the role it was issued under. grantedScopes is what the key was created holding, and roleId names the ceiling that narrowed it, so anything in the first list and missing from the second was removed by that role.

That difference is the answer to the confusing 403. A key created with emails:send and capped by a viewer role is refused for lacking emails:send, which reads as a lie against the key the console is displaying; the fix is to change the role rather than to mint another key. roleId is null on a key with no ceiling, which is what every key issued before roles existed still has.

Two independent lists narrow what the key may send as. 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. Both null or both empty means the key may send as any address the workspace owns. With either one 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 lists are written, so the two never overlap.

Mints a new secret for the key making the call and returns it once. There is no body and no way to name another key here: this call rotates the caller and nothing else, and POST /keys/{id}/rotate is the one that reaches other keys, behind keys:manage.

The old secret stops working the instant this returns. There is no overlap window and no grace period, and the response is the only place the new secret ever appears, so a caller that drops it has locked itself out until somebody in the console rotates the key again.

Everything else about the key is unchanged: same id, same name, same mode, same scopes, same role, same allowlists and same expiry. Only the last four characters move, because they are part of the secret. The request history hangs off the id rather than off the secret, so it runs straight through a rotation and reads as one key on both sides of it rather than as two.

Weigh that before granting keys:write. A stolen key holding it can rotate itself and take the secret away from the person who owns the key. It cannot hide while doing so, because the id does not move and revoking it from the console still works.

Requires the keys:write scope.

The request log of the key making the call, newest first: every authenticated call it made, with method, path, status, error code, duration, IP and user agent, never a body or a query string. Needs no scope: a key may always read its own log, and it reads no other key's here. GET /keys/{id}/requests and GET /keys/requests are the ones that reach other keys, behind keys:read.

failedOnly, status, path, since and until narrow it, and they combine. 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. The call that reads the log is logged too.

What happened to the key making the call, newest first: created, updated, rotated, deactivated, reactivated, and every attempt to authenticate with it that was refused. actor says who, a person as @username or a key as API key <name>, and detail.source where from. Needs no scope, and it reads no other key's history: GET /keys/{id}/activity and GET /keys/activity do that, behind keys:read. since and until narrow it.

What the key making the call did inside a window: the requests it made and how many failed, the calls refused because its secret was wrong, revoked or expired, the 8 routes it called most with the median time each took, and the status codes it got back. Needs no scope: a key may always read its own figures, and it reads no other key's here. GET /keys/stats is the one that reaches other keys.

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.