openemail keys

Returns one page of the workspace's keys, newest first, with what the Settings, API keys page shows: status, scopes, role, send scope, when each was last used, how often, and who made and last changed it. Revoked and expired keys stay listed until somebody deletes them. No secret is ever returned; maskedKey is enough to tell two keys apart.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

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.

Resolves with one key as list shows it. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

openemail.me.get() describes the calling key itself and needs no scope; this reads any key the caller can see.

Creates a live key and resolves with it plus token, the whole secret. That is the only time it appears, so store it before doing anything else.

Left out, scopes is ['emails:send'], the role is the caller's own or none, the send scope is the caller's own or none (none means every address the workspace owns), and the expiry is the caller's own or none. The workspace cap on live keys applies, as a 422 workspace_limit_reached.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

Step-up verification, which the app asks for before it mints a key, cannot apply to a call made with a key, so keys:manage is a credential that makes credentials. Give it only to automation that provisions keys, narrow that key to the role and send scope it needs, and give it an expiry.

Applies a partial change and resolves with the key as it now stands. scopes, --address-allowlist and --domain-allowlist REPLACE what the key had, and a field left out stays as it was. enabled: false switches the key off: every call with it is refused with inactive_api_key and it keeps its secret, scopes, role and send scope, so enabled: true restores it exactly. That is the reversible alternative to revoke. A revoked key cannot be changed, and answers 409 revoked.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis. A key changing itself may only narrow itself.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

Deletes a key that has already been revoked. Its request log and activity stay, under Deleted key, so the history of what it did is not lost with it. A key that has not been revoked is refused with 409 not_revoked, so nothing still calling with it loses its credential without somebody deciding that first.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

Mints a new secret for a key and resolves with the key plus token, rotationCount and rotatedAt. The id, name, scopes, role, send scope, expiry and request history all carry on; only the secret and keyLast4 change. There is no overlap window: the old secret stops working the instant this returns.

Rotating the calling key itself is what openemail.me.rotate() does, and here it is allowed with keys:write as well as keys:manage. A revoked or expired key cannot be rotated, and answers 409 revoked or expired.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis. Rotation hands the caller a working secret for the key, which is why the ceiling is checked against the key as it stands.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

Revokes a key: every later call with it is refused with revoked_api_key, and it can never be switched back on, rotated or changed. reason is kept on the key and in the activity log. Revoking a key that is already revoked changes nothing and resolves with it as it is. A key may revoke itself, which is how an integration that believes its secret leaked retires it at once.

A key never makes or reaches a key wider than itself. The target has to sit inside the caller on every axis: scopes the caller holds after its own role has narrowed them, the same role when the caller has one, an expiry no later than the caller's when the caller expires, the caller's mode, and a send scope inside the caller's own, where one address never covers its whole domain. Anything wider is 403 beyond_caller_authority, and param names the axis.

A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

Returns one page of the calls one key made, newest first, the Requests tab of the key in the app. The request log records every authenticated call a key made: method, path, status, error code, duration, IP and user agent, and never a body or a query string. A call refused before a key could be identified is not in it, and neither is a call made with an OAuth access token. Nothing is pruned, so the log reaches back to a key's first call. --failed-only, since and until are the filters the app offers.

A deleted key's log stays readable to a key that is not narrowed. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

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 one key's audit log, newest first, the Activity tab of the key in the app. Every change to a key is a row: created, updated, rotated, deactivated, reactivated, revoked and deleted, 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.

A deleted key keeps its history, readable to a key that is not narrowed. A key narrowed to some domains or addresses only sees the keys whose send scope sits inside its own, so any other is a 404 rather than a refusal. Over OAuth only the workspace owner reaches it, and a member's token is 403 owner_only.

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 every call the workspace's keys made, newest first, the Requests tab of Settings, API keys. The request log records every authenticated call a key made: method, path, status, error code, duration, IP and user agent, and never a body or a query string. A call refused before a key could be identified is not in it, and neither is a call made with an OAuth access token. Nothing is pruned, so the log reaches back to a key's first call. --key-ids, --failed-only, since and until are the filters the app offers, and --key-ids may name a deleted key.

A narrowed key reads only the log of the keys it can see, so naming another key in --key-ids matches nothing.

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 every key in the workspace, newest first, the Activity tab of Settings, API keys. Every change to a key is a row: created, updated, rotated, deactivated, reactivated, revoked and deleted, 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.

--key-ids narrows it, deleted keys included, and since and until keep a window. A narrowed key reads only the activity of the keys it can see.

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 numbers behind the Analytics tab of the API keys page: the mail the keys sent and what became of it, the calls refused because a secret was wrong, revoked or expired, the requests they made and how many failed, the routes they called most with the median time each took, and the status codes they got back.

It covers every key you can see, or the ones --key-ids names. 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.