Two-factor sign-in

A second step after every sign-in: six digits from an app on your phone, a backup code, or a passkey.

With two-factor sign-in on, someone who gets into your email, your GitHub or your Google account still cannot sign in to agental. It is off until you turn it on, and we suggest you do. Accounts that can open Admin need it.

Turn it on#

• In the console, under Settings, Signing in: Turn on.
• Scan the QR code with an authenticator app (1Password, Google Authenticator, Authy, or the passwords app on your phone), or type the key under it.
• Enter the six digits it shows. Two-factor sign-in is on, and every other session of yours is signed out.
• Save the ten backup codes it shows you, in your password manager. Each lets you in once, in place of the app, and they are not shown again.

Signing in#

Every way in asks for the second step: a code sent by email, GitHub, Google and a password alike. Enter the six digits the app shows now, or a backup code. On your own computer, slide “Trust this browser” to 6, 12 or 24 hours, or 3, 7 or 30 days, and it is not asked there again until then: logging in again meanwhile does not make the time longer. It starts at Off, which asks every time.

Each code from the app lets you in once. Sent again, at a sign-in or for a change, it is refused with “That code was used already”: wait the few seconds for the next one, or use a backup code. So someone who sees you type a code cannot use it after you.

The agental command signs in through your browser, so it asks there too, and letting it in asks for a code. Making an API key in the console asks for one as well, since a key outlives the session that made it, and so does letting a key be used from more places. Keys that are made already work as before: a key is its own credential.

Passkeys#

A passkey signs you in with Touch ID, Windows Hello, your phone or a security key: both steps at once, with nothing to type. Add one under Settings, Signing in. The device must check who holds it, by a fingerprint, a face or a PIN, and while two-factor sign-in is on, adding one asks for a code first.

On the log-in page, choose “Sign in with a passkey”, or “Use a passkey instead” at the second step.

Changing it#

• Turning it off, making ten new backup codes, making an API key, letting a key be used from more places, letting an SSH key in to every sandbox made from a template, letting the agental command in and ending sessions ask for a code from the app or a backup code. So do adding a box and turning off someone else's two-factor sign-in, for an operator. Five wrong codes in a quarter of an hour, wherever they are sent, and that session waits: another one, signed in afresh, does not, and a right code in between does not start the count again.
• Letting an SSH key in to one sandbox asks for none: a person signed in can run any command in it anyway, so a code would stop nothing.
• Settings says how many browsers are trusted and until when the last one is. “Forget them” asks every browser for the second step again.
• Each change is said by email to your account's address: on, off, and a passkey added or removed.
• These are changed only by a person signed in. An API key is refused with session_required.

Your sessions#

A session is one browser signed in. It ends 30 days after it signed in, however much it is used, and that browser signs in again.

• Settings, Signing in lists every session: its browser, the address it signed in from, when it signed in, when it was last used and when it ends. This browser's comes first.
• End one you do not know, or end all the others, and whoever used them is signed out at once. While two-factor sign-in is on, this asks for a code, so a session taken from a browser cannot end yours. Each time, your account's address is emailed which ones were ended.
• Think someone copied this browser's session? Log out: that ends it wherever it is used, and you sign in again.
• Only a person signed in sees or ends sessions. An API key is refused with session_required.

Lost your phone#

Sign in with a backup code, turn two-factor sign-in off with another one, and turn it on again with your new phone. Have only a passkey left, or nothing at all? Write to [email protected] from your account's address. Once we are sure it is you, we turn it off: your backup codes, passkeys and trusted browsers are removed, and every session is signed out. Then you sign in as before and set it up again.

With a password, from a script#

An account with a password that signs in through the API sends the second step as code, the six digits or a backup code:

{"email":"[email protected]","password":"…","code":"482913"}

Without it, such an account is answered 401 two_factor_required, with methods: what the second step may be done with.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]