Entity
Learn about the entity object in the PortierX API and how to interact with it.
Work in progress
We are actively working on our API. The documentation and implementation described here may not yet be fully aligned.
Overview
The entity object represents a real-world entity such as a person, organization, or device. Entities are used to store information about users, devices, and other entities in the PortierX system.
Common Attributes
All endpoints will use plural.
We are not provided a nested route. So instead of having /locations/{:id}/areas for all areas for locationSlug, you can get the value from /areas/?location={:id}. You can even add another filter like /areas/?location={locationSlug}&type=room to get all floors for locationSlug.
For :id in the endpoint, you can use the UUID representative or human readable ID (slug). So both
We use slug instead of id for the endpoint. So instead of /locations/1, you will have /locations/office-1.
The entity object has the following common attributes:
| Attribute | Type | Description |
|---|---|---|
id | UUID | The unique identifier of the entity. |
name | string | The name of the entity. |
slug | string | A human-readable identifier for the entity. |
created_at | string | The timestamp when the entity was created. |
created_by | string | The identifier of the user who created the entity. |
updated_at | string | The timestamp when the entity was last updated. |
updated_by | string | The identifier of the user who last updated the entity. |
Entity Definitions
Location Management
| Group | Entity | Description |
|---|---|---|
| Location Management | Location | Root entity for a working area. |
| Area | Subdivided spaces (buildings, floors, rooms, zones). | |
| Entrance | A guarded access point controlling entry to an area. |
Locking System Management
| Group | Entity | Description |
|---|---|---|
| Locking System Management | Locking System | A security system that groups multiple locks and policies. |
| Lock | A physical or electronic mechanism that secures an entrance. | |
| Key | Represents a credential (physical key, RFID, PIN, mobile ID, biometric) used to unlock locks. |
People Management
| Group | Entity | Description |
|---|---|---|
| People | Person | A physical individual who may hold keys but does not necessarily use the app. |
| User | A person who also has an app account to manage locks or access logs. | |
| Group | A collection of people categorized by function or location (e.g., "Finance Dept", "Building A Workers"). | |
| Role | Defines permission levels within a group (e.g., "Manager" in "Finance Dept", "Technician" in "IT Dept"). |
Rules & Logs
| Group | Entity | Description |
|---|---|---|
| Rules | Access Rule | Defines who can access what, based on keys and permissions. |
| Logs | Access History | Tracks historical access records (who had access to what and when). |
Endpoints
| Method | Endpoint | Description | Fields | Possible Database Tables |
|---|---|---|---|---|
| GET | /locations | List all locations for the current customer | id, name, type, address, status, created_at | locations |
| POST | /locations | Create a new location | name, type, address, geo_coordinates, status | locations |
| GET | /locations/{id} | Get details of a specific location | id, name, type, address, geo_coordinates, status, areas | locations, areas |
| PATCH | /locations/{id} | Update location details | name, type, address, geo_coordinates, status | locations |
| DELETE | /locations/{id} | Delete a location | id | locations |
| GET | /areas | Get all areas in an location | id, name, type, status, lock_id | areas |
| POST | /areas | Create an area inside an location | name, type, status, lock_id | areas |
| GET | /areas/{id} | Get details of a specific area | id, name, parent_id, type, status, children_areas | areas |
| PATCH | /areas/{id} | Update an area | name, parent_id, type, status | areas |
| DELETE | /areas/{id} | Delete an area | id | areas |
| GET | /entrances | Get all entrances in an area | id, name, type, status, lock_id | entrances |
| POST | /entrances | Create an entrance inside an area | name, type, status, lock_id | entrances |
| GET | /entrances/{id} | Get details of a specific entrance | id, name, type, status, lock_id, area_id | entrances |
| PATCH | /entrances/{id} | Update entrance details | name, type, status, lock_id | entrances |
| DELETE | /entrances/{id} | Delete an entrance | id | entrances |
Information /me /tenant /current /current/summary
Locking Systen /systems /locks /keys /key-profiles
Hold by zitadel /users /auth
Data Model Design
locations Table
| Column | Type | Description |
|---|---|---|
| id | UUID | Unique identifier |
| tenant_id | UUID | Links to the customer |
| name | VARCHAR | Location name |
| type | ENUM | office, warehouse, factory, building |
| address | TEXT | Full address |
| geo_coordinates | JSONB | { "lat": x, "long": y } |
| status | ENUM | active, inactive |
| created_at | TIMESTAMP | Timestamp |
areas Table
| Column | Type | Description |
|---|---|---|
| id | UUID | Unique identifier |
| location_id | UUID | Links to locations.id |
| parent_id | UUID (nullable) | Parent area (NULL if top level) |
| name | VARCHAR | Area name (e.g., "Level 2", "Main Hall") |
| type | ENUM | floor, room, hall, section |
| status | ENUM | active, inactive |
| depth_level | INT | Hierarchy level (e.g., 0 = building, 1 = floor, 2 = room) |
entrances Table
| Column | Type | Description |
|---|---|---|
| id | UUID | Unique identifier |
| area_id | UUID | Links to areas.id (defines where entrance exists) |
| name | VARCHAR | Entrance name (e.g., "Main Gate", "Backdoor") |
| type | ENUM | door, gate, turnstile, barrier |
| status | ENUM | active, inactive |
| lock_id | UUID (nullable) | If linked to a locking system |
| created_at | TIMESTAMP | Timestamp |