How do I set up two-factor authentication (2FA)?

Requires Basic

Quick answer

Open your Profile, go to the “Two-factor authentication” section, and click “Add device”. Give it a device name, scan the QR code with your authenticator app (or type in the key manually), and confirm with the 6-digit code. From then on, every login requires this code. You can register multiple devices — this is strongly recommended as a backup.

Prerequisites

Required role Signed-in user

— everyone sets up 2FA for themselves. You’ll need an authenticator app (e.g. Google Authenticator, Microsoft Authenticator, Aegis, 1Password). If your organization requires 2FA, you’re taken straight to setup right after logging in.

Instructions

GUI (web interface)

1. Open your profile. Click your user menu in the top right and choose “Profile”. Scroll to the “Two-factor authentication” section and click “Add device”.

   Screenshot pending erste-schritte-2fa-01 Profile section 'Two-factor authentication' with the 'Add device' button and the device list

   The 2FA section in the profile, with the 'Add device' button.

2. Name the device. Enter a device name (for example “iPhone” or “Authenticator”) and click “Next”. The name helps you tell multiple devices apart.

   Screenshot pending erste-schritte-2fa-02 'Add device' dialog, step 1: input field for the device name with a 'Next' button

   Step 1: give the new device a name.

3. Scan the QR code. Scan the displayed QR code with your authenticator app. If you can’t scan it, type the code shown under “Secret (manual)” into the app instead.

   Screenshot pending erste-schritte-2fa-03 'Add device' dialog, step 2: QR code with the manually enterable key below it and a field for the 6-digit code

   Step 2: scan the QR code or type in the key manually.

4. Confirm the code. Enter the current 6-digit code from the app and click “Confirm”. The device now appears in the list as “Active”. From this point on, 2FA is switched on for your account.

   Screenshot pending erste-schritte-2fa-04 2FA device list with one confirmed device and the 'Active' status marker

   After confirmation, the device is active — 2FA is switched on.

Multiple devices (recommended): Repeat the steps to register a second device (for example a tablet) as a backup. At login, a code from any of your confirmed devices is accepted.

Removing a device: Via the trash icon next to the device and a confirmation prompt. If you remove the last confirmed device, 2FA is automatically disabled.

Recovery / lockout: There are no backup codes. If you no longer have any device, an administrator can reset your 2FA in user management (removing all devices). This is exactly why you should register at least a second device.

API (curl)

Setup involves three calls: creating a device, confirming it with a code — and removing it again if needed. The endpoints apply to your own account (logged-in session or personal API token).

List existing devices

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/auth/totp/devices

Create a new device (returns secret + QR code)

curl -X POST https://demo.notory.io/api/v1/auth/totp/devices \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "iPhone" }'

The response includes the secret once, along with an otpauth:// URI and the QR code as a base64 PNG:

Response (201 Created, abridged)

{
  "device_id": "9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33",
  "name": "iPhone",
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/max.mustermann@example.com%20(iPhone)?secret=JBSWY3DPEHPK3PXP&issuer=Notory",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA…"
}

Confirm the device with a current code from the app:

Confirm the device

curl -X POST https://demo.notory.io/api/v1/auth/totp/devices/9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33/verify \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Response (200 OK)

{ "message": "Device confirmed; two-factor authentication is active" }

You remove a device with DELETE (response 204 No Content):

Remove the device

curl -X DELETE https://demo.notory.io/api/v1/auth/totp/devices/9f2c1a7e-3b44-4c90-8e21-7d6a0b1c2e33 \
  -H "Authorization: Bearer inv_dein_token"

Possible errors: 400 (invalid code when confirming), 404 (device not found), 401 (not logged in / invalid token).

What happens behind the scenes?

• Multiple devices: You can create any number of named devices. Each has its own secret and must be confirmed individually with a code. At login, the code is checked against every confirmed device — a matching code from any one of them is enough.
• Activation: 2FA switches on as soon as the first device is confirmed (totp_enabled).
• Automatic deactivation: If you remove the last confirmed device, 2FA is switched off automatically.
• Enforced 2FA: If your instance or tenant requires 2FA, Notory blocks all functionality after login until you’ve confirmed a device (setup screen).
• No backup codes: There is no recovery-code system. If you lose all your devices, an administrator resets your 2FA (endpoint users/{id}/totp).
• Secret shown only once: The secret is only ever returned when the device is created and is never issued again via the API.
• Audit log: Confirming a device is logged; for each device, last_used_at is updated on every successful use.

Related topics

• Log in — the 2FA prompt at login
• Manage your profile
• Users & Roles — administrator resets 2FA
• SSO / OIDC — an alternative to password-based login