Nullgap.dev Docs

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

WhatWhoWhere in the console
Authenticator app, recovery codes, passkeys, your sessionsEach personYour profile (/settings/profile), under Security
Require multi-factor sign-in, sign everyone outAdminSettings, 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

  1. On your profile, under Authenticator app, choose Set up an authenticator app.
  2. 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.
  3. Enter the 6-digit code the app shows and choose Turn on.
  4. 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: 400 mfa_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.

FactValue
How manyTen per set
FormTwo groups of five characters, for example k3n7a-q2x5m
UsesEach code works once, anywhere an authenticator code is asked for
StorageNullgap keeps only hashes of them. They cannot be shown again
New setCreate 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

  1. On your profile, under Passkeys, choose Add a passkey.
  2. Give it a name, such as the device or password manager that keeps it.
  3. 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 400 enrol_first;
  • the change asks for a fresh second-factor check. Switching it off does too.

What members experience:

MemberEffect
Has an authenticator app or a passkeyNothing changes
Has neitherEvery 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-onLet 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 403 step_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:

ActionRole
Change a member's roleAdmin (owner for owner roles)
Switch Require multi-factor sign-in on or offAdmin
Sign everyone outAdmin
Create an outbound webhook, or rotate its signing secretAdmin
Create, rotate or revoke an API keyOwner
Save or remove single sign-onOwner
Issue or replace the SCIM token, or turn SCIM offOwner
Connect GitLab, Bitbucket Cloud, Azure DevOps or GitHub Enterprise ServerOwner
Rotate a code-host connection's webhook secretOwner
Set up the Slack assistant, save its signing secret, or remove itOwner
Erase dataOwner

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 429 mfa_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_rejected for each wrong code and mfa.locked when 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.

ShownMeaning
Browser and systemThe family only, such as "Chrome on macOS"
Network addressShortened before it is stored, so it shows roughly where a session came from, not the exact device
Sign-in methodGitHub, single sign-on, sign-in link or passkey
Second step verifiedThe session passed a second-factor check
This sessionThe 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_all with 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