Policies

Create or update a policy with a specified ID

PUT
https://ditto.eclipseprojects.io/api/2/policies/{policyId}

Create or update the policy specified by the policyId path parameter.

  • If you set a new policyId in the path, a new policy will be created.
  • If you set an existing policyId in the path, the policy will be updated.

Create a new policy

At the initial creation of a policy, at least one valid entry is required. However, you can create a full-fledged policy all at once.

By default the authorized subject needs WRITE permission on the root resource of the created policy. You can however omit this check by setting the parameter allow-policy-lockout to true.

Example: To create a policy for multiple coffee maker things, which gives yourself all permissions on all resources, set the policyId in the path, e.g. to "com.acme.coffeemaker:policy-01" and the body part, like in the following snippet.

{
  "entries": {
    "DEFAULT": {
      "subjects": {
        "{{ request:subjectId }}": {
          "type": "the creator"
        }
      },
      "resources": {
        "policy:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        },
        "thing:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        },
        "message:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    }
  },
  "imports": {
    "com.acme:importedPolicy" : {
      "entries": [ "IMPORTED" ]
    }
  }
}

Update an existing policy

For updating an existing policy, the authorized subject needs WRITE permission on the policy's root resource.

The ID of a policy cannot be changed after creation. Any policyId specified in the request body is therefore ignored.

Partially update an existing policy

Partial updates are not supported.

If you need to create or update a specific label, resource, or subject, please use the respective sub-resources.

Body

application/json

JSON representation of the policy. Use the placeholder {{ request:subjectId }} in order to let the backend insert the authenticated subjectId of the HTTP request.

Policy consisting of policy entries

entriesPolicyEntriesrequired

Policy entries containing one policy entry for each arbitrary label key

Show child attributes
label1PolicyEntry

Single policy entry. Both subjects and resources are optional — they default to empty when absent. An entry may define references to inherit subjects, resources, and namespaces from other entries (local or imported).

Show child attributes
subjectsSubjects

A SubjectEntry defines who is addressed.

Show child attributes
nginx:subjectId1SubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
nginx:subjectIdNSubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
resourcesResources

(Authorization) Resources containing one ResourceEntry for each type:path key, type being one of the following thing, policy, message.

Show child attributes
[key: string]ResourceEntry

Single (Authorization) Resource entry defining permissions per effect. Allowed effects are grant and revoke.

Show child attributes
grantArray<Permission>READWRITE
revokeArray<Permission>READWRITE
Example
{
  "thing:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "thing:/attributes/some/path": {
    "grant": null,
    "revoke": [
      "READ"
    ]
  },
  "policy:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "message:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  }
}
namespacesArray<string>

Restricts this policy entry to things whose namespace matches at least one pattern. If omitted or empty, the entry applies to all namespaces.

  • com.acme matches only that exact namespace
  • com.acme.* matches namespaces below com.acme, but not com.acme itself
Example
[
  "com.acme",
  "com.acme.*"
]
importableImportableimplicitexplicitneverimplicit

Controls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy.

  • implicit (default): the policy entry is imported without being listed in the importing policy individually
  • explicit: the policy entry is only imported if it is listed in the importing policy
  • never: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is implicit.
Example
explicit
allowedAdditionsArray<string>subjectsresourcesnamespaces

Defines which types of additions are allowed when this entry is referenced by other entries via references.

Semantics:

  • Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default.
  • Field present and empty ([]) — no additions allowed; only the referenced entry's content is effective.
  • Field present with values — only the listed kinds of additions survive on the referencing entry.

This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference.

  • subjects — allows referencing entries to add additional subjects on top of this entry
  • resources — allows referencing entries to add additional resources on top of this entry
  • namespaces — allows referencing entries to add additional namespace patterns on top of this entry
Example
[
  "subjects"
]
referencesArray<object>

An optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry.

  • Import reference: contains both entry (the label) and import (the policy ID of the imported policy)
  • Local reference: contains only entry (the label of another entry in the same policy)
Show child attributes

A single reference to a policy entry.

entrystringrequired

The label of the referenced entry.

importstring

The ID of the imported policy this reference points to. If absent, the reference points to a local entry within the same policy.

labelNPolicyEntry

Single policy entry. Both subjects and resources are optional — they default to empty when absent. An entry may define references to inherit subjects, resources, and namespaces from other entries (local or imported).

Show child attributes
subjectsSubjects

A SubjectEntry defines who is addressed.

Show child attributes
nginx:subjectId1SubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
nginx:subjectIdNSubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
resourcesResources

(Authorization) Resources containing one ResourceEntry for each type:path key, type being one of the following thing, policy, message.

Show child attributes
[key: string]ResourceEntry

Single (Authorization) Resource entry defining permissions per effect. Allowed effects are grant and revoke.

Show child attributes
grantArray<Permission>READWRITE
revokeArray<Permission>READWRITE
Example
{
  "thing:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "thing:/attributes/some/path": {
    "grant": null,
    "revoke": [
      "READ"
    ]
  },
  "policy:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "message:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  }
}
namespacesArray<string>

Restricts this policy entry to things whose namespace matches at least one pattern. If omitted or empty, the entry applies to all namespaces.

  • com.acme matches only that exact namespace
  • com.acme.* matches namespaces below com.acme, but not com.acme itself
Example
[
  "com.acme",
  "com.acme.*"
]
importableImportableimplicitexplicitneverimplicit

Controls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy.

  • implicit (default): the policy entry is imported without being listed in the importing policy individually
  • explicit: the policy entry is only imported if it is listed in the importing policy
  • never: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is implicit.
Example
explicit
allowedAdditionsArray<string>subjectsresourcesnamespaces

Defines which types of additions are allowed when this entry is referenced by other entries via references.

Semantics:

  • Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default.
  • Field present and empty ([]) — no additions allowed; only the referenced entry's content is effective.
  • Field present with values — only the listed kinds of additions survive on the referencing entry.

This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference.

  • subjects — allows referencing entries to add additional subjects on top of this entry
  • resources — allows referencing entries to add additional resources on top of this entry
  • namespaces — allows referencing entries to add additional namespace patterns on top of this entry
Example
[
  "subjects"
]
referencesArray<object>

An optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry.

  • Import reference: contains both entry (the label) and import (the policy ID of the imported policy)
  • Local reference: contains only entry (the label of another entry in the same policy)
Show child attributes

A single reference to a policy entry.

entrystringrequired

The label of the referenced entry.

importstring

The ID of the imported policy this reference points to. If absent, the reference points to a local entry within the same policy.

importsPolicyImports

Policy imports containing one policy import for each key. The key is the policy ID of the referenced policy.

Show child attributes
policyImport1PolicyImport

Single policy import defining which policy entries of the referenced policy are imported.

Show child attributes
entriesArray<string>

The policy entries to import from the referenced policy identified by their labels. In case the field is omitted or an empty array is provided, all policy entries defined as implicit ("importable": "implicit") are imported.

transitiveImportsArray<string>

List of policy IDs from the imported policy's own imports that should be resolved transitively before extracting entries. This enables multi-level import chains where a template policy defines resources and an intermediate policy defines entries with "references" that add local subjects.

Each entry is the policy ID of a policy that the directly imported policy itself imports from. Only the listed policy IDs are resolved — this is an explicit whitelist, not a recursive flag.

Example
[
  "org.eclipse.ditto:policy-template"
]
Example
{
  "entries": [
    "default",
    "import"
  ]
}
policyImportNPolicyImport

Single policy import defining which policy entries of the referenced policy are imported.

Show child attributes
entriesArray<string>

The policy entries to import from the referenced policy identified by their labels. In case the field is omitted or an empty array is provided, all policy entries defined as implicit ("importable": "implicit") are imported.

transitiveImportsArray<string>

List of policy IDs from the imported policy's own imports that should be resolved transitively before extracting entries. This enables multi-level import chains where a template policy defines resources and an intermediate policy defines entries with "references" that add local subjects.

Each entry is the policy ID of a policy that the directly imported policy itself imports from. Only the listed policy IDs are resolved — this is an explicit whitelist, not a recursive flag.

Example
[
  "org.eclipse.ditto:policy-template"
]
Example
{
  "entries": [
    "default",
    "import"
  ]
}
Example
{
  "com.acme:policyId1": {
    "entries": [
      "label1",
      "label2"
    ]
  },
  "com.acme:policyId2": {
    "entries": [
      "import"
    ]
  },
  "com.acme:policyId3": {}
}

Parameters

policyIdstringrequiredpath

The ID of the policy needs to follow the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).

The namespace needs to:

  • conform to the reverse domain name notation
If-Matchstringheader

The If-Match header, which has to conform to RFC-7232 (Conditional Requests). Common usages are:

  • optimistic locking by specifying the ETag from a previous GET response, e.g. If-Match: "rev:4711"
  • retrieving or modifying a resource only if it already exists, e.g. If-Match: *
If-None-Matchstringheader

The If-None-Match header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying If-None-Match: *.

if-equalstringupdateskipskip-minimizing-mergeheader

The if-equal header can take the values 'update' (which is the default if omitted), 'skip' or 'skip-minimizing-merge'. If 'update' is defined, the entity will always be updated, even if it is equal before the update. If 'skip' is defined, the entity not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. If 'skip-minimizing-merge' is defined, the entity will not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. Additionally, merge/patch commands will be minimized to only the fields which actually changed, compared to the current state of the entity.

timeoutstringquery

Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested acknowledgements via the requested-acks param. Can be specified without unit (then seconds are assumed) or together with s, ms or m unit. Example: 42s, 1m.

The default (if omitted) and maximum timeout is 60s. A value of 0 applies fire and forget semantics for the command resulting in setting response-required=false.

response-requiredbooleanquery

Defines whether a response is required to the API call or not - if set to false the response will directly sent back with a status code of 202 (Accepted).

The default (if ommited) response is true.

allow-policy-lockoutbooleanquery

Defines whether a subject is allowed to create a policy without having WRITE permission on the policy resource of the created policy.

The default (if ommited) is false.

Response

201CreatedNewPolicy

The policy was successfully created.

Response headers
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

Locationstringheader

The location of the created policy resource

Response fields application/json

Policy consisting of policy entries

entriesPolicyEntriesrequired

Policy entries containing one policy entry for each arbitrary label key

Show child attributes
label1PolicyEntry

Single policy entry. Both subjects and resources are optional — they default to empty when absent. An entry may define references to inherit subjects, resources, and namespaces from other entries (local or imported).

Show child attributes
subjectsSubjects

A SubjectEntry defines who is addressed.

Show child attributes
nginx:subjectId1SubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
nginx:subjectIdNSubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
resourcesResources

(Authorization) Resources containing one ResourceEntry for each type:path key, type being one of the following thing, policy, message.

Show child attributes
[key: string]ResourceEntry

Single (Authorization) Resource entry defining permissions per effect. Allowed effects are grant and revoke.

Show child attributes
grantArray<Permission>READWRITE
revokeArray<Permission>READWRITE
Example
{
  "thing:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "thing:/attributes/some/path": {
    "grant": null,
    "revoke": [
      "READ"
    ]
  },
  "policy:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "message:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  }
}
namespacesArray<string>

Restricts this policy entry to things whose namespace matches at least one pattern. If omitted or empty, the entry applies to all namespaces.

  • com.acme matches only that exact namespace
  • com.acme.* matches namespaces below com.acme, but not com.acme itself
Example
[
  "com.acme",
  "com.acme.*"
]
importableImportableimplicitexplicitneverimplicit

Controls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy.

  • implicit (default): the policy entry is imported without being listed in the importing policy individually
  • explicit: the policy entry is only imported if it is listed in the importing policy
  • never: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is implicit.
Example
explicit
allowedAdditionsArray<string>subjectsresourcesnamespaces

Defines which types of additions are allowed when this entry is referenced by other entries via references.

Semantics:

  • Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default.
  • Field present and empty ([]) — no additions allowed; only the referenced entry's content is effective.
  • Field present with values — only the listed kinds of additions survive on the referencing entry.

This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference.

  • subjects — allows referencing entries to add additional subjects on top of this entry
  • resources — allows referencing entries to add additional resources on top of this entry
  • namespaces — allows referencing entries to add additional namespace patterns on top of this entry
Example
[
  "subjects"
]
referencesArray<object>

An optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry.

  • Import reference: contains both entry (the label) and import (the policy ID of the imported policy)
  • Local reference: contains only entry (the label of another entry in the same policy)
Show child attributes

A single reference to a policy entry.

entrystringrequired

The label of the referenced entry.

importstring

The ID of the imported policy this reference points to. If absent, the reference points to a local entry within the same policy.

labelNPolicyEntry

Single policy entry. Both subjects and resources are optional — they default to empty when absent. An entry may define references to inherit subjects, resources, and namespaces from other entries (local or imported).

Show child attributes
subjectsSubjects

A SubjectEntry defines who is addressed.

Show child attributes
nginx:subjectId1SubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
nginx:subjectIdNSubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes
typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes
beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes
labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example
{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}
randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example
{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}
Example
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
resourcesResources

(Authorization) Resources containing one ResourceEntry for each type:path key, type being one of the following thing, policy, message.

Show child attributes
[key: string]ResourceEntry

Single (Authorization) Resource entry defining permissions per effect. Allowed effects are grant and revoke.

Show child attributes
grantArray<Permission>READWRITE
revokeArray<Permission>READWRITE
Example
{
  "thing:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "thing:/attributes/some/path": {
    "grant": null,
    "revoke": [
      "READ"
    ]
  },
  "policy:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "message:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  }
}
namespacesArray<string>

Restricts this policy entry to things whose namespace matches at least one pattern. If omitted or empty, the entry applies to all namespaces.

  • com.acme matches only that exact namespace
  • com.acme.* matches namespaces below com.acme, but not com.acme itself
Example
[
  "com.acme",
  "com.acme.*"
]
importableImportableimplicitexplicitneverimplicit

Controls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy.

  • implicit (default): the policy entry is imported without being listed in the importing policy individually
  • explicit: the policy entry is only imported if it is listed in the importing policy
  • never: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is implicit.
Example
explicit
allowedAdditionsArray<string>subjectsresourcesnamespaces

Defines which types of additions are allowed when this entry is referenced by other entries via references.

Semantics:

  • Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default.
  • Field present and empty ([]) — no additions allowed; only the referenced entry's content is effective.
  • Field present with values — only the listed kinds of additions survive on the referencing entry.

This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference.

  • subjects — allows referencing entries to add additional subjects on top of this entry
  • resources — allows referencing entries to add additional resources on top of this entry
  • namespaces — allows referencing entries to add additional namespace patterns on top of this entry
Example
[
  "subjects"
]
referencesArray<object>

An optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry.

  • Import reference: contains both entry (the label) and import (the policy ID of the imported policy)
  • Local reference: contains only entry (the label of another entry in the same policy)
Show child attributes

A single reference to a policy entry.

entrystringrequired

The label of the referenced entry.

importstring

The ID of the imported policy this reference points to. If absent, the reference points to a local entry within the same policy.

importsPolicyImports

Policy imports containing one policy import for each key. The key is the policy ID of the referenced policy.

Show child attributes
policyImport1PolicyImport

Single policy import defining which policy entries of the referenced policy are imported.

Show child attributes
entriesArray<string>

The policy entries to import from the referenced policy identified by their labels. In case the field is omitted or an empty array is provided, all policy entries defined as implicit ("importable": "implicit") are imported.

transitiveImportsArray<string>

List of policy IDs from the imported policy's own imports that should be resolved transitively before extracting entries. This enables multi-level import chains where a template policy defines resources and an intermediate policy defines entries with "references" that add local subjects.

Each entry is the policy ID of a policy that the directly imported policy itself imports from. Only the listed policy IDs are resolved — this is an explicit whitelist, not a recursive flag.

Example
[
  "org.eclipse.ditto:policy-template"
]
Example
{
  "entries": [
    "default",
    "import"
  ]
}
policyImportNPolicyImport

Single policy import defining which policy entries of the referenced policy are imported.

Show child attributes
entriesArray<string>

The policy entries to import from the referenced policy identified by their labels. In case the field is omitted or an empty array is provided, all policy entries defined as implicit ("importable": "implicit") are imported.

transitiveImportsArray<string>

List of policy IDs from the imported policy's own imports that should be resolved transitively before extracting entries. This enables multi-level import chains where a template policy defines resources and an intermediate policy defines entries with "references" that add local subjects.

Each entry is the policy ID of a policy that the directly imported policy itself imports from. Only the listed policy IDs are resolved — this is an explicit whitelist, not a recursive flag.

Example
[
  "org.eclipse.ditto:policy-template"
]
Example
{
  "entries": [
    "default",
    "import"
  ]
}
Example
{
  "com.acme:policyId1": {
    "entries": [
      "label1",
      "label2"
    ]
  },
  "com.acme:policyId2": {
    "entries": [
      "import"
    ]
  },
  "com.acme:policyId3": {}
}
204No Content

The policy was successfully updated.

Response headers
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

400Bad RequestAdvancedError

The request could not be completed. Possible reasons:

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

401UnauthorizedAdvancedError

The request could not be completed due to missing authentication.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

403ForbiddenAdvancedError

The request could not be completed. Possible reasons:

  • the caller has insufficient permissions. You need WRITE permission on the root policy:/ resource, without any revoke in a deeper path of the policy resource. (You can omit this check by setting the allow-policy-lockout parameter.)
Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

404Not FoundAdvancedError

The request could not be completed. The policy with the given ID or policy referenced in a policy import was not found in the context of the authenticated user.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

412Precondition FailedAdvancedError

A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a failing If-None-Match header for a read request, status 304 will be returned instead.

Response headers
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

413Payload Too LargeAdvancedError

The created or modified entity is larger than the accepted limit of 100 kB.

Response fields application/json
statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

Authorization

OpenIDConnectopenIdConnect

OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.

NginxBasichttp (basic)

Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)

Bearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Docs by Sourcey
↑↓ navigate↵ selectesc close