How do I create a user — and what happens behind the scenes?

Requires Basic

Short answer

Open Administration → User Management, click “Add User”, and fill in Email, Username, Display name, an initial password, and the Role. Once saved, the user exists immediately — in the currently active tenant, with the chosen role, and active by default. Creating a user does not automatically send an invitation: the administrator sets the initial password. You can then optionally invite the user by e-mail (a secure one-time link) or send them a password reset link.

Requirements

Required role Administrator

— creating users requires the Administrator role (require_role(“admin”)). A super admin can additionally assign the user to a different tenant. Programmatically, the API token needs the write scope and must belong to an administrator account.

User management is part of the core product and is included in all plans. Sending e-mail (invitations, reset links) requires a configured SMTP server; without SMTP you can still create users, but you can only assign the password directly.

Instructions

GUI (web interface)

1. Open User Management. In the navigation, go to Administration, then to User Management (the Users tab). You’ll see the list of all users in your tenant, with their role, status (Active), and last login. The “Add User” button sits at the top.

   Screenshot pending admin-benutzer-01 User management with the user list and the highlighted 'Add User' button

   User management, with the 'Add User' button.

2. Fill in the form. The “Add User” form opens. The required fields are:

   • Email — must be valid and unique system-wide (it’s the sign-in name).
   • Username — 3–128 characters, also unique.
   • Display name — the full name (e.g. “Lena Vogt”).
   • Password — at least 8 characters. Serves as the initial password (see the box below).
   • Role — Administrator, Manager, Technician, or Viewer (default: Viewer).

   The Active toggle determines whether the user can sign in immediately (default: active).

   Screenshot pending admin-benutzer-02 Empty 'Add User' form with email, username, display name, password and role selection

   The 'Add User' form. Email, username, display name, password and role are required.

3. Save. Click “Save”. The user is created and appears in the list. Clicking the entry opens the user detail page (/admin/users/…), where you can later assign roles, set the password, or reset 2FA.

   Screenshot pending admin-benutzer-03 Detail page of the freshly created account, with Account, Password and 2FA sections

   After creation: the new user's detail page, with the Account, Password and Two-Factor sections.

Inviting by e-mail (optional). If you’d rather not tell the user their password out loud, open the detail page after creating the account, go to the Password section, and choose “E-mail the new password to the user” or “Send reset link”. Both options require a configured SMTP server — see Reset a password administratively for details.

API (curl)

The same action via the REST API: a POST to /api/v1/users with an administrator’s bearer token (scope write). The required fields are email, username, password, and full_name; role and is_active have default values.

Create a user

curl -X POST https://demo.notory.io/api/v1/users \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "lena.vogt@example.com",
    "username": "lvogt",
    "password": "Anfangs-Kennwort-2026",
    "full_name": "Lena Vogt",
    "role": "manager",
    "is_active": true
  }'

On success, the API responds with HTTP 201 Created. The password is never returned — the response contains only metadata:

Response (201 Created)

{
  "id": "018f9b2c-6a41-7e02-9d3b-2c1a4f7e0055",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "email": "lena.vogt@example.com",
  "username": "lvogt",
  "full_name": "Lena Vogt",
  "role": "manager",
  "is_active": true,
  "is_superadmin": false,
  "totp_enabled": false,
  "last_login": null,
  "created_at": "2026-07-08T09:14:22Z",
  "updated_at": "2026-07-08T09:14:22Z"
}

To then invite the user by e-mail (instead of telling them the password directly), set their password with send_email — Notory then sends a secure one-time link instead of plain text:

Invite a user (password via one-time link)

curl -X POST https://demo.notory.io/api/v1/users/018f9b2c-6a41-7e02-9d3b-2c1a4f7e0055/password \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "new_password": "Anfangs-Kennwort-2026", "send_email": true }'

Alternatively, you can send only a reset link, letting the user choose their own password:

Send a reset link to the user

curl -X POST https://demo.notory.io/api/v1/users/018f9b2c-6a41-7e02-9d3b-2c1a4f7e0055/password-reset-link \
  -H "Authorization: Bearer inv_dein_token"

Possible errors: 401 (token missing/invalid), 403 (not an administrator / missing write scope), 409 (email or username already taken), 422 (validation failure — e.g. password shorter than 8 characters, or invalid email), 503 (e-mail delivery was requested, but no SMTP is configured).

What happens behind the scenes?

Creating a user is more than just a database entry. Several steps happen in the background — and some things aren’t decided until the new user’s first login.

On save

• Uniqueness check. Email and username are global keys. If either is already taken, Notory aborts with 409 Conflict — before anything is saved.
• Password hashing with Argon2id. The password is never stored in plain text; it’s hashed immediately with Argon2id (parameters: time_cost=3, memory_cost=64 MiB, parallelism=4). The hash never appears in API responses or backups either.
• Tenant assignment. The user is assigned to the currently active tenant (tenant_id from your session). Only a super admin may specify a different tenant_id when creating the user. A user always belongs to exactly one tenant.
• Role & permissions. The chosen role determines the base permissions (see Roles & permissions). If none is specified, Viewer applies (read-only). Additional, fine-grained permissions can later be assigned via custom roles.
• Audit log. The creation is recorded in the audit log (action create, entity users) — with the triggering user, tenant, IP address, timestamp, and a running hash chain for tamper detection. You can review it under Administration → Audit Log.

Password handover: direct or by invitation

Notory deliberately supports two ways for the initial password to reach the user:

• Assigned directly (default when creating a user). The password entered in the form is the user’s real initial password. They sign in with it — without a forced change. Suitable when you hand over the password personally/securely.
• Invite by e-mail (the “set password + e-mail” action, i.e. send_email: true). Here, Notory internally sets the “password change required” flag and never sends plain text: the password is stored on a One-Time-Secret instance, and the user only receives a one-time link (“Show password”). If no one-time-link service is reachable, Notory automatically falls back to a reset link (the user chooses their own password) — never to plain text.

What the new user experiences at first login

• Sign-in with email and password. After five failed attempts, the account is locked for 15 minutes.
• Mandatory password change. If the user was invited by e-mail (flag set), after logging in they can only reach the change-password, own-profile, and sign-out areas. Every other request is blocked with 403 and the message “You must change your password before continuing”, until they’ve set a password of their own.
• Mandatory 2FA (if enabled). If two-factor is enforced instance-wide or for the tenant, the user can sign in, but is immediately forced to set up an authenticator device (“Two-factor authentication required — your organisation requires 2FA”). Until a device is confirmed, only the setup, profile, and sign-out endpoints are reachable. So 2FA is not assigned at creation time — it’s completed at first login.
• Created deactivated? If Active was unchecked, every sign-in attempt fails with “Account is deactivated” until an administrator activates the account.

What does NOT happen

• Simply creating a user sends no e-mail — invitation and reset are deliberately separate, explicit actions.
• No webhook is triggered: Notory currently sends webhook events only for assets, not for user creation (see Webhooks).

Related topics

• Understanding roles & permissions — what Administrator, Manager, Technician and Viewer are allowed to do
• Create a custom role — fine-grained permissions via RBAC
• Reset a password administratively — set a password, invitation, reset link
• Deactivate or delete a user
• Set up SSO / OIDC — signing in without a local password
• API introduction — authentication, base URL, error codes