openemail.security

Tells an app connected with OAuth whether it may make sensitive changes right now. The web app asks a person for a verification code before a change that could lock them out or leak mail, and an app acting for that person is asked the same thing. An API key is never asked, so this call is for OAuth access tokens only.

elevated is true while a code verified through verifyStepUp still holds, and elevatedUntil says when that ends, or is null when there is nothing to end. The elevation belongs to this app acting for this person, and it holds for the app's MCP calls as well as for REST: the MCP tools that make the same guarded changes, such as createRule and removeDomain, run while it lasts. Another app they connected has to verify on its own, and signing in to the web app does not count here. The person can also allow this app from the website, with Allow changes for 60 minutes on the app in Account settings, Connected apps, and elevated is then true here as well.

method is how the next code would be checked. It is totp when the person has two-factor sign-in turned on, and then the code comes from their authenticator app, or is one of their backup codes. Otherwise it is email, and beginStepUp emails a code to the address they sign in with. minutes is how long an elevation lasts once a code is verified, currently 60.

Call it before a batch of sensitive changes to ask for a code once, up front, rather than waiting for the first 403 step_up_required.

Opens a verification challenge for an app connected with OAuth. Call it when a request fails with 403 step_up_required, or before a batch of sensitive changes, then pass the code the person gives you to verifyStepUp.

method says where the code comes from. With email a six digit code has just gone to the address the person signs in with, sentTo names that address with most of it hidden, such as a•••@example.com, and the code works for 10 minutes. The email says a connected app asked for the code and shows the name this app registered with, its client ID, the date the person connected it and, when the app was refused one in the last 15 minutes, the change it last asked to make, so they can see which app is asking before they hand the code over. It also tells them the code unlocks more than one change: for 60 minutes the app can make any change that needs a code and that they gave it access to. With totp nothing is sent: the person has two-factor sign-in turned on and reads the code from their authenticator app, or uses one of their backup codes.

A challenge that is still open and still has tries left is reused rather than replaced, so calling this twice does not send two emails. reused is true when that happened, and the code sent the first time is the one to enter. Pass resend: true to close the open challenge and start a new one, which emails a fresh code. A challenge that five wrong codes locked is never reused, and neither is one that expired, so after step_up_code_expired, or after the fifth wrong code, a plain beginStepUp() starts a fresh challenge without resend.

Each app has a budget of its own with each person: 5 new challenges an hour and 20 in 24 hours. Another app never uses it up, and neither does the person working in the web app, whose own budget is 10 codes an hour.

Wrong codes count against the app too. After 10 in 24 hours, across every challenge it opened, verification is paused for this app. After 20 in 24 hours from all the apps the person connected together, it is paused for every one of them, this app included, even if none of those codes came from it, and removing an app does not lift that pause. Codes entered in the web app count toward neither, and the person can still verify there. While a pause lasts, this call and verifyStepUp answer 429 step_up_locked with a message that says verification is paused until a given time, and no code is sent or checked before then.

An API key is never asked for a code, so this call is for OAuth access tokens only.

Checks the code the person entered against the challenge beginStepUp opened, and on a match lets this app make sensitive changes for them until elevatedUntil, 60 minutes from now. Replay the request that failed with 403 step_up_required once this resolves.

The verification belongs to this app acting for this person. It unlocks the 16 changes that ask for a code: webhooks.create, webhooks.update, rules.create, rules.update, roles.update, roles.delete, members.add, members.update, members.remove, members.grantAddress, members.revokeAddress, domains.delete, domains.deleteAddress, appHost.delete, audiences.delete and forms.delete. Each still needs the scope it always needs. It holds for the MCP tools that make the same changes as well (createRule, setRuleEnabled, removeDomain, removeDomainAddress, removeAppHost, deleteForm, and deleteAudience on any audience but the default one), which answer Refused (step_up_required) while the app is not verified. Nothing else asks for a code, audiences.empty and the emptyAudience tool included. Another app the person connected verifies on its own.

The code is the one emailed to them when the method is email, or a code from their authenticator app, or one of their backup codes, when it is totp. Spaces are ignored, so a code copied as 123 456 works. An authenticator code is accepted only once: entering one that was already accepted, by any app or in the web app, counts as a wrong code, so wait for the next one.

Open a challenge with beginStepUp first, even when the code comes from an authenticator app, because the code is checked against that challenge. A challenge allows five tries. The fifth wrong code locks it, and a locked challenge is never reused, so the next beginStepUp() starts a fresh one without resend.

Wrong codes also count against this app for 24 hours, across every challenge, and a correct code does not clear them. The tenth in 24 hours pauses verification for this app. They count toward a second limit as well, shared by every app the person connected: the twentieth wrong code in 24 hours from all of those apps together pauses verification for every one of them, this app included, even if none of those codes came from it. Removing an app from the person's connected apps does not lift that pause. Codes entered in the web app count toward neither limit, and the person can still verify there during either pause. While a pause lasts, this call and beginStepUp answer 429 step_up_locked with a message that says verification is paused until a given time, and until then even a correct code is refused.

An app that has no way to ask the person for a code, such as an MCP connector that only calls tools, does not need this call: the person can choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the website, which lets it make the same changes for 60 minutes. They can end that early from the same menu.

An API key is never asked for a code, so this call is for OAuth access tokens only.