User Entity (Semantic Module)

← Back to Modules Reference

The User semantic module is the core identity tag used to mark the main user account table (such as Customers or Employees) in your API.

Applying this module is generally required for all APIs (unless your API is entirely public, like a product catalog or a demo project). It automatically enables account creation, user sign-in, permissions (roles), and tracking who owns what data.

---

Technical Specifications

Attribute	Specification
Scope	Entity (Applied to a whole table/entity)
Setup Limit	Exactly One User table per API is allowed

---

How It Works Automatically

1. User Sign-in & Authentication

Tagging a table with User tells the system: “This is the list of people who can log in.” When someone signs in, the platform automatically looks up their credentials in this table.

2. Auto-tracking Ownership

When users create records (like placing an order or writing a comment), the system automatically links those records to the active user who created them. This makes it easy to secure data so users can only view or edit their own items.

3. Enables Current User (/me) Endpoints

Tagging your entity with User is the prerequisite for configuring Current User endpoints (/users/me) in the API Modeler. This generates singleton endpoints (GET /users/me, PATCH /users/me, DELETE /users/me) where the authenticated user’s ID is resolved and injected dynamically from their active session.

---

Guidelines for Designing Your User Table

To support sign-in and security, your User table should include fields tagged with these standard options:

• Username: The field used to log in (like an email address or a unique username handle).
• Password: The secure password field. The platform automatically encrypts this so it is never readable.
• UserRole: The field that sets permissions (like Admin or Member) to control what actions users are allowed to perform.

---

Database Architecture & Multi-API Reusability

All APIs within an organization run on a single, unified PostgreSQL database. To handle table isolation and data sharing across multiple APIs cleanly, the platform uses automatic domain prefixing and catalog reuse:

1. Automatic Table Prefixing (Private Tables per API)

• Every Data Domain automatically generates a unique prefix (derived from its domain key) for all of its physical database tables.
• By default, every entity table (including User) is private to its own API, eliminating table name collisions across different APIs in your organization.
• Within a single API, only one entity can be designated as the User table.

2. Sharing Unified Users Across APIs via Data Domain Reuse

If you have multiple APIs that need to operate on the exact same user base (for example, a public Customer API and an internal Admin API):

1. Define your User entity inside a dedicated Data Domain (e.g., auth or identity-core).
2. Publish that Data Domain to the Data Catalog with Organization scope.
3. Import that published domain into your other API domains (e.g., Storefront domain and Admin domain).

When a Data Domain is imported and reused across multiple APIs, the runtime preserves the original domain prefix. All importing APIs reference and operate on the exact same physical database table (see Multi-API & Database Reuse).

---

API Lifecycle Example

User Registration (POST /auth/register)

User registration and credential management are handled directly by the platform-managed /auth endpoints. When registering a new account, the client sends credentials to /auth/register:

POST /auth/register
{
  "email": "alex.mercer@example.com",
  "password": "SecurePassword123!"
}

Server Response

The database creates the user record, securely hashes the password, applies default roles, and returns the newly registered profile:

{
  "data": {
    "id": "usr_998231",
    "email": "alex.mercer@example.com",
    "role": "Member",
    "created_at": "2026-06-28T13:10:00Z"
  }
}

Direct create Action Disabled

The standard create action is disabled for the User entity to ensure account creation always passes through the platform’s secure credential hashing and identity verification pipeline.

---

Validation Warnings & Errors

The platform will automatically check your design to prevent configuration issues:

• Multiple Users Error: If you try to tag more than one table as the User in a single API, the system will show an error and prompt you to remove the duplicate tags.
• Missing Username or Password: If you tag a table as the User but forget to define a Username or Password field, the system will show a warning reminding you to add them so your users can log in.