Docs / Contact / iam/policies

Policies

Policies define fine-grained access rules that control what actions users can perform on which resources. Policies use an IAM-style statement format with namespaced actions.

The editor has two views of the same policy. Policy Builder is the visual form — pick an effect, a resource, and the actions to grant, grouped by namespace — and JSON is the raw statement document for anything the form does not cover, such as conditions written by hand. Switching views never changes the policy; they are two windows onto one document.

Access Control → Policies → Add. This statement grants read and directory actions on 480512:us-1:dir:plant-a — a directory-scoped policy covering every device under /plant-a.

Policy Structure

A policy contains one or more statements. Each statement specifies:

JSON Format

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["entity:ListEntities", "entity:GetEntities"],
      "Resource": "*"
    }
  ]
}

The JSON view of the editor shows this document directly and edits are applied back to the builder, so you can start in the form and finish by hand. Validate Policy checks the document the way the API will before you save it.

Access Control → Policies → Add → JSON.

Resource Paths

Resources use the format {accountNumber}:{region}:{resourceType}:{resourceName}. For example:

• 12345:us-1:entity:sensor-01
• 12345:us-1:connector:my-http-connector
• 12345:us-1:service:temperature-service

Use * to match all resources.

Conditions

A condition narrows when a statement applies. Each operator takes a map of field → value, and there are exactly three fields:

and three operators:

Example — grant access only to entities named sensor-*:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["entity:GetEntities", "entity:ListMessages"],
      "Resource": "*",
      "Condition": {
        "StartsWith": {
          "Resource": "12345:us-1:entity:sensor-"
        }
      }
    }
  ]
}

A Contains condition (e.g. "Resource": "entity:sensor-") is a convenient alternative when you want to match a name fragment without hard-coding the account number and region.

Subject conditions and cross-account writes

A Subject condition constrains who the statement applies to. This is the only way to admit a write from another account: a same-account grant, however broad, never authorizes a cross-account writer. The destination account must opt in explicitly, per source:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["entity:WriteMessages"],
      "Resource": "67890:us-1:*",
      "Condition": {
        "StartsWith": { "Subject": "12345:us-1:" }
      }
    }
  ]
}

Attached to a role on account 67890, this accepts writes from account 12345 and no one else. Without the Subject condition the statement grants nothing across accounts, no matter how permissive it looks.

Action Namespaces

Actions are namespaced by resource type (namespace:Verb). This is the authoritative reference for the actions Contact enforces.

Entity (entity:)

Fanout (fanout:)

fanout:CreateFanouts, fanout:ListFanouts, fanout:GetFanouts, fanout:UpdateFanouts, fanout:DeleteFanouts, fanout:PublishToFanout

Directory (directory:)

directory:CreateDirectories, directory:ListDirectories, directory:GetDirectories, directory:UpdateDirectories, directory:DeleteDirectories, directory:MoveEntities

directory:MoveEntities covers filing an entity into a directory or removing it from one. See Directories for how a directory-scoped policy works.

Alert (alert:)

alert:CreateAlerts, alert:ListAlerts, alert:GetAlerts, alert:UpdateAlerts, alert:DeleteAlerts

Dashboard (dashboard:)

dashboard:CreateDashboards, dashboard:ListDashboards, dashboard:GetDashboards, dashboard:UpdateDashboards, dashboard:DeleteDashboards, dashboard:QueryWidgetData

dashboard:QueryWidgetData is what a dashboard widget uses to fetch its series; a role that can view dashboards but lacks it will render empty widgets.

Notification (notification:)

notification:ListNotifications, notification:UpdateNotifications

Flow / Connector (flow:)

flow:ListFlows, flow:GetFlows, flow:ListConnectors, flow:GetConnectors, flow:CreateConnectors, flow:UpdateConnectors, flow:DeleteConnectors

Service (service:)

service:ListServices, service:GetServices, service:CreateServices, service:UpdateServices, service:DeleteServices

IAM (iam:)

Insights (insights:)

insights:GetInsights covers all insights endpoints (messages, entities, validation, flows, data usage, summary).

Built-in Policies

Contact includes three built-in policies that cannot be modified or deleted:

Policy Evaluation

• Deny statements always take precedence over Allow statements
• If no policy explicitly allows an action, it is denied by default
• Policies are attached to roles, not directly to users

Policy Inheritance

A policy can name another policy as its parent. The child then starts from everything the parent grants and adds its own statements on top — useful for a house baseline that several roles extend, since editing the baseline updates every policy built on it.

Set a parent in the policy editor with Inherit from an existing policy, or pass parentPolicyId when creating a policy through the API.

The rules, in order:

1. A child adds to its parent. Every grant the child does not mention is

inherited unchanged.

2. Deny wins — for the actions it names, and only those. If a child denies

entity:WriteMessages on a resource its parent allowed for several actions, only entity:WriteMessages is denied; the rest of the inherited grant stands.

3. A child cannot lift an inherited Deny. Re-allowing an action the parent

denies has no effect. To grant it, remove the Deny from the parent.

4. Conditional grants accumulate. Two statements for the same action and

resource whose conditions differ are two independent grants; both apply. A child adding a Subject condition does not replace the parent's.

5. Chains resolve top-down, to any depth. A grandparent's grant reaches the

child unless something below denies it.

6. Cycles are rejected. A policy cannot inherit from itself, directly or

through a chain.

Directory-Scoped Policies

A statement whose Resource is a directory path covers every entity filed in that directory and below:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["entity:GetEntities", "entity:ListMessages", "entity:UpdateEntities"],
      "Resource": "12345:us-1:dir:plant-a"
    }
  ]
}

Grant this and the holder can work with every entity under /plant-a, including anything filed into /plant-a/line-3 later. You never list devices individually, and moving a device between directories moves its access with it.

Matching is exact on path segments: a policy naming /plant does not cover /plant-a. Directory resource paths are shown under each folder in the Directories rail.

Directory scoping covers the full device surface: reading, updating and deleting entities, filing them into folders, and the per-device action endpoints — reboot, the remote command console and filesystem access, SDK pinning, provisioning-key rotation, status-table writes, and publishing to or managing the membership of a fanout filed in the subtree. Code deployments are scoped per target: a deploy to a mixed set delivers to the devices the grant covers and reports denied for the rest.

← Back to Contact docs