Core Concepts

This page introduces the building blocks of ErtisAuth and how they relate to each other. Each concept has its own reference page with the full details.

Installation
└── Membership (tenant)
    ├── Users ──────────── have a Role, a User Type, and optional own permissions
    ├── User Types ─────── the schema of user data, with inheritance
    ├── Roles ──────────── named sets of permissions
    ├── Applications ───── machine clients, have a Role and optional own permissions
    ├── Providers ──────── Google, Apple, Facebook, Microsoft sign-in
    ├── Code Policies ──── format of device sign-in codes
    ├── Events ─────────── the log of what happened
    ├── Webhooks ───────── HTTP calls triggered by events
    └── Mail Hooks ─────── emails triggered by events

Membership#

A membership is an isolated tenant, like a realm in Keycloak. Everything else belongs to exactly one membership, and a token issued in one membership can't access the resources of another one.

A membership also holds the settings of its users' authentication:

• the lifetimes of access, refresh, scoped and reset tokens,
• the secret key the tokens are signed with,
• the password hash algorithm and the text encoding,
• the mail providers, the activation policy, the OTP settings and the device code policy.

One installation can host many memberships, for example one per product or per customer. See Memberships.

User#

A user is a person who signs in. Every user has:

• a username and an email_address, both unique in the membership (either can be used to sign in),
• a role, which grants most of their permissions,
• a user_type, which defines which other fields the user has,
• optional permissions and forbidden lists of their own (UBAC),
• an is_active flag: inactive users can't sign in.

See Users.

User type#

A user type is the schema of a kind of user, for example Customer or Employee. It declares the custom fields (a phone number, a birth date, a list of addresses…) with their types and validation rules. User types can inherit from each other; all of them ultimately inherit from the built-in base-user type, which declares the standard fields (firstname, lastname, username, email_address, role…).

See User Types.

Role#

A role is a named set of permissions (permissions) and denials (forbidden), shared by many users and applications. The setup creates the reserved admin role, which can do everything.

See Roles and Authorization.

Application#

An application is a machine client: a backend service, a scheduled job, a server-side web app. It authenticates with a Basic token made of its id and a secret, and like a user it has a role and optional permissions of its own.

See Applications.

Utilizer#

Utilizer is ErtisAuth's word for whoever makes a request: a user (with a Bearer token) or an application (with a Basic token). Events record the utilizer who caused them, and permissions are evaluated for the utilizer.

Tokens#

See Authentication.

Provider#

A provider connects an external identity provider (Google, Apple, Facebook, Microsoft) to a membership. Users who sign in with it are created on their first sign-in, or linked to an existing account.

See External Identity Providers.

Events, webhooks and mail hooks#

Most operations record an event: a user was created, a token was generated, a role was updated… Events can be read through the API, and they trigger:

• webhooks, which send an HTTP request to a URL of your choice,
• mail hooks, which send a templated email.

See Events, Webhooks and Mail Hooks.

Identifiers and slugs#

• Every resource has an _id (a MongoDB ObjectId string).
• Memberships, roles, applications, user types, providers, webhooks, mail hooks and code policies also have a slug: a URL-friendly name derived from the name when you don't set one. A slug can't contain whitespace and can't start with a digit.
• Where a resource is referred to by another one, the slug is used: a user's role and user_type are slugs, as are a provider's defaultRole and defaultUserType.
• The single-resource endpoints of memberships, roles, applications, user types and providers accept either the id or the slug.

The sys field#

Resources carry a sys object maintained by the server:

"sys": {
	"created_at": "2026-01-01T12:00:00Z",
	"created_by": "admin",
	"modified_at": "2026-01-02T08:30:00Z",
	"modified_by": "backend"
}

created_by and modified_by hold the username of the user, or the slug of the application, who made the change (system for changes made by ErtisAuth itself, such as the setup or a provider sign-up). A sys sent in a request body is ignored. All dates are in UTC.