ClientIPAddress (Semantic Module)

← Back to Modules Reference

The ClientIPAddress semantic module automatically records the public IP address of the client making an API request.

It functions as an immutable, system-managed audit field. You do not need to read request headers or parse proxy forwards in application code; the Serverless Engine extracts the client IP reliably and populates the property during database writes while preventing clients from spoofing or tampering with the value.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text or string property)
Data Type	String
Value Source	System-extracted from request context (X-Forwarded-For / connection IP)
Access Control	Read-Only / System-Managed (Client writes are rejected)
Lifecycle Hooks	Populated automatically on Create and Update actions

---

Automatic Backend Actions

1. Zero-Trust Client Injection Fencing

To guarantee the authenticity of your security logs, clients are strictly forbidden from manually providing or altering IP addresses:

• If an incoming POST, PUT, or PATCH request includes a value for a property tagged with ClientIPAddress, the engine halts the request and returns a 400 Bad Request error:

  {
    "type": "https://docs.apinow.app/errors/validation",
    "title": "Validation Error",
    "status": 400,
    "code": "E_VALIDATION_ERROR",
    "detail": "Property 'ip_address' is managed by the platform and cannot be manually modified."
  }

2. Automatic Reverse-Proxy IP Extraction

When requests arrive through API gateways, load balancers, or Cloudflare, the Serverless Engine inspects standard proxy headers (such as X-Forwarded-For and CF-Connecting-IP) to capture the true client IP rather than the load balancer’s internal subnet address.

---

Common Use Cases

• Security & Access Auditing: Keeping an untamperable historical log of which IP address initiated sensitive business actions (such as initiating payouts, modifying billing settings, or signing legal agreements).
• Fraud & Abuse Detection: Detecting account takeover attempts, bot spam, or rapid credential stuffing from suspicious IP subnets.
• Geolocation & Compliance: Enriching customer login records with geographic country or region lookups for regional data sovereignty and compliance.

---

API Lifecycle Walkthrough

Assume an entity named LoginAttempt has a property ip_address decorated with the ClientIPAddress semantic module.

Step 1: Submitting a Request

The client submits the regular business data without providing an IP:

POST /login-attempts
Content-Type: application/json

{
  "username": "alice@example.com",
  "status": "success"
}

Step 2: Server Response

The Serverless Engine automatically extracts the client’s IP from the HTTP connection and writes it to the database record:

HTTP/1.1 201 Created

{
  "data": {
    "id": "att_8129",
    "username": "alice@example.com",
    "status": "success",
    "ip_address": "203.0.113.195",
    "created_at": "2026-09-15T14:10:00Z"
  }
}

---

Modeling Guidelines

• Property Length Constraints: String properties in the Domain Modeler default to a Maximum Length of 255 characters, which comfortably accommodates both IPv4 (up to 15 characters) and full IPv6 addresses (up to 45 characters). If you customize the property’s Maximum Length constraint, ensure it is set to at least 45 characters.
• Property Exposure: Because client IPs may constitute Personally Identifiable Information (PII) under privacy regulations (such as GDPR), consider using Field Projections or Data Access Rules to restrict read exposure to admin or compliance roles.