الحساب

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.