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.

---

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 Rules & Multi-API Constraints

Within a single organization, the platform sets up a single database to run all your APIs. Because of this, there are a few important rules to keep in mind:

1. One User Table Rule

You cannot have more than one table designated as the User table inside the same API. However, you can have different tables for different user groups (like user_customers and user_employees) if they are managed in separate APIs.

2. Best Practice: Reusing Users via the Data Catalog

If you have multiple APIs that need to share the same list of users:

1. Define your User table in a dedicated Data Domain (a schema project).
2. Publish that Data Domain to the Data Catalog.
3. Import that published User module into your other specialized APIs.

This ensures all your APIs use a single, consistent user list instead of creating duplicate tables.

---

API Lifecycle Example

User Registration (Request)

When creating a new user record, standard HTTP requests are routed to the model’s collection endpoint:

POST /users
{
  "name": "Alex Mercer",
  "email": "alex.mercer@example.com",
  "password": "SecurePassword123!",
  "role": "Member"
}

Server Response

The database creates the record, encrypts the password, normalizes the username, and returns the profile without returning the password value:

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

---

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.