Skip to content

Tendrl Entities: Device-to-Device Communication

Overview

Entity

Entities are the core device construct in the Tendrl platform that enable secure, role-based communication between any devices on the network. Every entity represents a physical or virtual device (IoT sensor, server, microcontroller, etc.) that can send and receive messages through the Tendrl platform.

What is an Entity?

An entity is essentially a device identity that consists of:

  • Unique identifier - A name that identifies the device within an account
  • Role assignment - Each entity is assigned a role that defines its permissions. The role contains policies that govern what the entity can do.
  • Authentication credentials - API keys that allow the entity to authenticate
  • Service - Data Validation Service (optional)
  • Metadata - JSON object for filtering or storing state (Optional)

Entity Creation UI Entity Creation UI Entity creation in the UI.

You can also define entities using JSON, as shown below:

{
  "name": "basic-entity",
  "role": "DefaultEntity",
  "enabled": true
}

Key Characteristics

  • Account-scoped: Entities belong to a specific Tendrl account
  • Role-based: Each entity has exactly one role that defines its capabilities
  • Policy-driven: All actions are authorized through the auth service using RBAC policies
  • Cross-account capable: Entities can communicate across account boundaries if policies allow

Entity Communication Model

Message Routing

When an entity sends a message, the dest (destination) field determines where the message goes:

Same Account Communication

{
  "msg_type": "publish",
  "dest": "sensor-01",
  "data": {
    "temperature": 23.5,
    "humidity": 65
  }
}
  • Destination: sensor-01 (just the entity name)
  • Behavior: Message sent to sensor-01 within the same account

Cross-Account Communication

{
  "msg_type": "publish", 
  "dest": "78901233:us-1:gateway-hub",
  "data": {
    "alert": "Temperature threshold exceeded",
    "value": 45.2
  }
}
  • Destination: 78901233:us-1:gateway-hub (account:region:entity)
  • Behavior: Message sent to gateway-hub in account 78901233 in the us-1 region

Role-Based Access Control (RBAC)

How RBAC Works for Entities

  1. Entity Creation: When an entity is created, it's assigned a role
  2. Policy Evaluation: The role contains policies that define allowed actions
  3. Authorization Check: Every message/action is validated by the auth service
  4. Cross-Account Security: Policies can grant or deny cross-account communication

Authentication & Authorization Flow

1. Entity Authentication Flow

  1. Get Claims: Entity calls POST /api/claims with its API key
  2. Receive JWT: Auth service returns JWT claims containing JTI (unique identifier)
  3. WebSocket Connection: Entity connects to WebSocket using the JTI
  4. Permission Validation: Platform validates entity permissions with auth service
  5. Connection Established: If authorized, WebSocket connection is established

2. Message Authorization Flow

  1. Send Message: Entity sends message to Tendrl platform with destination
  2. Authorization Check: Platform requests authorization from auth service for entity:WriteMessages action
  3. Policy Evaluation: Auth service evaluates entity's role policies against the request
  4. Authorization Decision: Auth service returns allow/deny decision
  5. Message Delivery: If authorized, message is delivered to destination entity
  6. Response: Success or denial response sent back to sending entity

Cross-Account Message:

{
  "msg_type": "publish",
  "dest": "789012:us-east:alert-processor",
  "data": {
    "alert_type": "motion_detected",
    "location": "Building A - Floor 2",
    "severity": "medium",
    "timestamp": "2025-01-09T15:30:00Z"
  }
}

Security Considerations

Policy Best Practices

  1. Principle of Least Privilege: Grant entities only the minimum permissions needed
  2. Resource Specificity: Use specific resource paths rather than wildcards when possible
  3. Conditional Access: Use conditions to restrict access based on context
  4. Cross-Account Restrictions: Carefully control cross-account permissions

Example Secure Policy

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["entity:WriteMessages"],
      "Resource": "{accountNumber}:{region}:entity:data-collector",
      "Condition": {
        "StartsWith": {
          "Subject": "{accountNumber}:{region}:entity:sensor-"
        }
      }
    },
    {
      "Effect": "Deny", 
      "Action": ["entity:WriteMessages"],
      "Resource": "*:*:entity:admin-*"
    }
  ]
}

This policy:

  • ✅ Allows sensors to send data to the data collector
  • ✅ Restricts to entities with names starting with "sensor-"
  • ❌ Explicitly denies access to any admin entities

Integration with SDKs

All Tendrl SDKs support entity operations:

The entity system provides a powerful, secure foundation for IoT and device-to-device communication, enabling complex distributed systems with fine-grained access control through RBAC policies.