Administration
Multi-factor sign-in and passkeys
Set up an authenticator app or a passkey, require a second factor for your organisation, and manage sessions.
Nullgap has no passwords. People sign in with an e-mail link, their GitHub account, a passkey, or your identity provider, depending on what is available. A second factor adds a step that proves the person is really there: a code from an authenticator app, or a passkey.
This page covers what each person sets up on their own account, what an admin can require for the organisation, and how sessions are managed.
#Where things are
| What | Who | Where in the console |
|---|---|---|
| Authenticator app, recovery codes, passkeys, your sessions | Each person | Your profile (/settings/profile), under Security |
| Require multi-factor sign-in, sign everyone out | Admin | Settings, Access, Sign-in |
A second factor belongs to a person's account, not to an organisation. It applies wherever that person signs in.
#Authenticator apps
Any app that implements time-based one-time passwords (TOTP) works: 6-digit codes that change every 30 seconds.
#Set one up
- On your profile, under Authenticator app, choose Set up an authenticator app.
- Scan the QR code with the app, or copy the key into it. Some apps accept the set-up link instead; it contains the same secret.
- Enter the 6-digit code the app shows and choose Turn on.
- Save the recovery codes that appear. This is the only time they are shown.
When the authenticator is confirmed, your other sessions are signed out. They were started without a second factor and must sign in again.
If your account already has a passkey, starting this set-up first asks you to confirm with it.
#How codes are checked
- A code is accepted for the current 30-second step and one step either side, to allow for clock drift.
- A code that was accepted once cannot be used again.
- A wrong code, a reused code and a malformed code all get the same answer:
400mfa_invalid.
#Turning it off
Turn off asks for a current code or a recovery code. It removes the authenticator and its recovery codes. Passkeys on the account stay.
If an organisation you belong to requires multi-factor sign-in and you have no passkey either, you cannot open that organisation until you set a second factor up again.
#Recovery codes
Recovery codes are for the day you lose your authenticator.
| Fact | Value |
|---|---|
| How many | Ten per set |
| Form | Two groups of five characters, for example k3n7a-q2x5m |
| Uses | Each code works once, anywhere an authenticator code is asked for |
| Storage | Nullgap keeps only hashes of them. They cannot be shown again |
| New set | Create new recovery codes, confirmed with a current code. The old set stops working |
The profile shows how many codes are left and warns when two or fewer remain. Using a recovery code is written to the audit log as mfa.recovery_code_used.
Recovery codes belong to the authenticator app. If you use only passkeys, register two of them (a phone and a laptop, for example), or also set up an authenticator app.
#Passkeys
A passkey signs you in with your fingerprint, face, screen lock or a security key. The device checks that it is you before it answers, so a passkey counts as both factors:
- Sign in with a passkey on the sign-in page signs you in completely, with no code.
- After another sign-in method, a passkey can answer the second step instead of a code.
- A passkey can confirm a sensitive action (the step-up check below).
- An account with a passkey and no authenticator app still meets an organisation's multi-factor requirement.
#Add a passkey
- On your profile, under Passkeys, choose Add a passkey.
- Give it a name, such as the device or password manager that keeps it.
- Confirm in your browser's prompt.
Facts to know:
- An account can hold up to 20 passkeys.
- Adding and removing a passkey need a fresh second-factor check when the account already has a second factor. Renaming does not.
- The first passkey on an account with no other second factor signs out your other sessions, as setting up an authenticator does.
- A passkey is tied to the address of your Nullgap console. It does not work on any other site.
- Only the passkey's public key is stored.
- The list shows whether a passkey is Synced by your password manager or platform account, or lives on This device only.
#Requiring multi-factor sign-in for the organisation
With Require multi-factor sign-in on (requireMfa in the organisation's settings), every member must have a second factor on their account before they can open the organisation.
To switch it on you need to be an admin, and:
- your own account must already have a second factor, otherwise the change is refused with
400enrol_first; - the change asks for a fresh second-factor check. Switching it off does too.
What members experience:
| Member | Effect |
|---|---|
| Has an authenticator app or a passkey | Nothing changes |
| Has neither | Every request to the organisation answers 403 mfa_required until they set one up. The console sends them to their profile to do it |
| Signed in through the organisation's single sign-on | Let in without a second factor in Nullgap. Your identity provider enforces its own policy |
API keys are not affected: a key has no person behind it.
Because changing requireMfa needs a signed-in person, it cannot be done with an API key. Reading the setting can:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"
Look for "requireMfa": true in the answer.
#The step-up check
Some actions are sensitive enough that a signed-in session is not sufficient on its own. They need a second factor to have been checked in the last 15 minutes.
- If your session passed a second-factor check less than 15 minutes ago, the action goes through.
- Otherwise the API answers
403step_up_required, and the console asks for your authenticator code, a recovery code or your passkey, then repeats the action. - If your account has no second factor, there is nothing to check and the action goes through. This is one reason to require multi-factor sign-in.
- An API key is always refused with
403: "API keys cannot do this. Sign in to the console."
#Actions that need it
Organisation actions:
| Action | Role |
|---|---|
| Change a member's role | Admin (owner for owner roles) |
| Switch Require multi-factor sign-in on or off | Admin |
| Sign everyone out | Admin |
| Create an outbound webhook, or rotate its signing secret | Admin |
| Create, rotate or revoke an API key | Owner |
| Save or remove single sign-on | Owner |
| Issue or replace the SCIM token, or turn SCIM off | Owner |
| Connect GitLab, Bitbucket Cloud, Azure DevOps or GitHub Enterprise Server | Owner |
| Rotate a code-host connection's webhook secret | Owner |
| Set up the Slack assistant, save its signing secret, or remove it | Owner |
| Erase data | Owner |
Actions on your own account:
- starting or confirming the set-up of an authenticator app, when the account already has a passkey;
- adding a passkey, when the account already has a second factor;
- removing a passkey.
Turning the authenticator off and creating new recovery codes do not use the 15-minute window. They always ask for a code in the same request.
#Lockout after wrong codes
Five wrong codes in a row lock the account's code check for 15 minutes.
- While locked, every code is refused with
429mfa_locked, including correct ones and recovery codes. - A correct code resets the count.
- The lock covers authenticator and recovery codes wherever they are asked for: at sign-in, at a step-up check and when changing the authenticator. Passkeys are checked separately and still work.
- The audit log records
mfa.code_rejectedfor each wrong code andmfa.lockedwhen a code is refused because of the lock.
There is no way to lift a lock early. Wait, or use a passkey.
#Sessions
#How long a session lasts
A session ends when it has not been used for a while, and in any case after a fixed time since sign-in. By default that is 12 hours without use and 7 days in total; the service can be configured with other values. After the first sign-in step, you have 10 minutes to complete the second.
#Your own sessions
On your profile, Sessions lists every browser where you are signed in.
| Shown | Meaning |
|---|---|
| Browser and system | The family only, such as "Chrome on macOS" |
| Network address | Shortened before it is stored, so it shows roughly where a session came from, not the exact device |
| Sign-in method | GitHub, single sign-on, sign-in link or passkey |
| Second step verified | The session passed a second-factor check |
| This session | The one you are using |
End session ends one. Sign out other sessions ends all but the one you are using. Both are recorded in the audit log (session.revoked, session.revoked_others).
Sessions also end on their own when your account's sign-in strength changes: setting up an authenticator, or adding a first passkey, signs out your other sessions.
#Signing everyone out
An admin can end the sessions of every member of the organisation: Settings, Access, Sign-in, Sign everyone out.
- Every member has to sign in again, on every device. Because a session belongs to a person, this also signs them out of any other organisation they were using.
- You stay signed in in the browser you are using.
- Reviews and pentests that are running are not affected, and API keys keep working.
- It asks for a fresh second-factor check, and the audit log records
session.revoked_allwith the number of sessions.
Use it after removing someone, or when a device may be compromised. To cut off programmatic access as well, revoke or rotate the API keys.
The API operations for everything on this page are listed in the multi-factor sign-in, passkeys and sessions references. They act on the signed-in person's own account, so they are used by the console and not with API keys.
Nullgap documentation