# Create or modify the entries of a specific Label of a specific policy `PUT /api/2/policies/{policyId}/entries/{label}` Create or modify the policy entry identified by the `policyId` path parameter and with the label identified by the `label` path parameter. * If you specify a new label, the respective policy entry will be created * If you specify an existing label, the respective policy entry will be updated Authentication (security requirement alternatives): ```json [ { "OpenIDConnect": [] }, { "NginxBasic": [] }, { "Bearer": [] } ] ``` - OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured. - NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo) - Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider. Parameters: - `policyId` (path, string, required) - The ID of the policy needs to follow the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)). The namespace needs to: * conform to the reverse domain name notation Type: string - `label` (path, string, required) - The label of a policy entry Type: string - `If-Match` (header, string, optional) - 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 HTTP response, e.g. `If-Match: "hash:a75ece4e"` * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *` Type: string - `If-None-Match` (header, string, optional) - 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: *`. Type: string - `if-equal` (header, string, optional) - 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. Type: string enum: ["update","skip","skip-minimizing-merge"] - `timeout` (query, string, optional) - 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`. Type: string - `response-required` (query, boolean, optional) - 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`. Type: boolean Request body: application/json (required) JSON representation of the policy entry. Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request. ### Example Given your policy "com.acme.coffeemaker:policy-01" only has the DEFAULT entry, and you want to add a "Consumer" section which additionally allows USER-01 (managed within a Nginx reverse proxy) to *read* the thing and to trigger a "makeCoffee" operation (i.e. POST such a message - see POST /things/{thingId}/inbox/messages/{messageSubject}). Set the label value to **Consumer** and the following request body: ``` { "subjects": { "nginx:USER-01": { "type": "pre authenticated user from nginx" } }, "resources": { "thing:/": { "grant": [ "READ" ], "revoke": [] }, "message:/": { "grant": [ "WRITE" ], "revoke": [] } } } ``` Type: PolicyEntry 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). Schema: [PolicyEntry](https://sourcey-ditto.pages.dev/http-api-doc/models/policyentry.md) - `subjects` (optional) Reference: [Subjects](https://sourcey-ditto.pages.dev/http-api-doc/models/subjects.md); Type: Subjects A SubjectEntry defines who is addressed. - `resources` (optional) Reference: [Resources](https://sourcey-ditto.pages.dev/http-api-doc/models/resources.md); Type: Resources (Authorization) Resources containing one ResourceEntry for each `type:path` key, `type` being one of the following `thing`, `policy`, `message`. Example: ```json { "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 } } ``` - `namespaces` (optional) Type: Array 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: ```json [ "com.acme", "com.acme.*" ] ``` Items: Type: string - `importable` (optional) Reference: [Importable](https://sourcey-ditto.pages.dev/http-api-doc/models/importable.md); Type: Importable 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`. default: "implicit" enum: ["implicit","explicit","never"] Example: ```json "explicit" ``` - `allowedAdditions` (optional) Reference: [AllowedAdditions](https://sourcey-ditto.pages.dev/http-api-doc/models/allowedadditions.md); Type: Array 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: ```json [ "subjects" ] ``` - `references` (optional) Reference: [References](https://sourcey-ditto.pages.dev/http-api-doc/models/references.md); Type: Array 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) Example: ```json [ { "entry": "operator", "import": "energy-corp:power-plant-roles" }, { "entry": "local-admin" } ] ``` ```json { "subjects": { "{{ request:subjectId }}": { "type": "the creator" } }, "resources": { "policy:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "thing:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "message:/": { "grant": [ "READ", "WRITE" ], "revoke": [] } } } ``` Responses: - 201: The policy entry was successfully created. Content type: application/json Type: PolicyEntry 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). Schema: [PolicyEntry](https://sourcey-ditto.pages.dev/http-api-doc/models/policyentry.md) - `subjects` (optional) Reference: [Subjects](https://sourcey-ditto.pages.dev/http-api-doc/models/subjects.md); Type: Subjects A SubjectEntry defines who is addressed. - `resources` (optional) Reference: [Resources](https://sourcey-ditto.pages.dev/http-api-doc/models/resources.md); Type: Resources (Authorization) Resources containing one ResourceEntry for each `type:path` key, `type` being one of the following `thing`, `policy`, `message`. Example: ```json { "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 } } ``` - `namespaces` (optional) Type: Array 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: ```json [ "com.acme", "com.acme.*" ] ``` Items: Type: string - `importable` (optional) Reference: [Importable](https://sourcey-ditto.pages.dev/http-api-doc/models/importable.md); Type: Importable 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`. default: "implicit" enum: ["implicit","explicit","never"] Example: ```json "explicit" ``` - `allowedAdditions` (optional) Reference: [AllowedAdditions](https://sourcey-ditto.pages.dev/http-api-doc/models/allowedadditions.md); Type: Array 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: ```json [ "subjects" ] ``` - `references` (optional) Reference: [References](https://sourcey-ditto.pages.dev/http-api-doc/models/references.md); Type: Array 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) Example: ```json [ { "entry": "operator", "import": "energy-corp:power-plant-roles" }, { "entry": "local-admin" } ] ``` - 204: The policy entry was successfully updated. - 400: The request could not be completed. Possible reasons: * the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)) * the JSON body of the policy entry to be created/modified is invalid Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 401: The request could not be completed due to missing authentication. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 403: The request could not be completed. Possible reasons: * the caller has insufficient permissions. You need `WRITE` permission on the `policy:/entries/{label}` resource, without any revoke in a deeper path of the policy resource. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 404: The request could not be completed. The policy with the given ID was not found in the context of the authenticated user. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 412: 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. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it - 413: The created or modified entity is larger than the accepted limit of 100 kB. Content type: application/json Type: AdvancedError Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md) - `status` (required) Type: integer The HTTP status of the error - `error` (required) Type: string The error code of the occurred exception - `message` (required) Type: string The message of the error - what went wrong - `description` (optional) Type: string A description how to fix the error or more details - `href` (optional) Type: string A link to further information about the error and how to fix it ## Examples ### cURL ```bash curl -X PUT 'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string' \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "subjects": { "{{ request:subjectId }}": { "type": "the creator" } }, "resources": { "policy:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "thing:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "message:/": { "grant": [ "READ", "WRITE" ], "revoke": [] } } }' ``` ### JavaScript ```javascript const body = `{ "subjects": { "{{ request:subjectId }}": { "type": "the creator" } }, "resources": { "policy:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "thing:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "message:/": { "grant": [ "READ", "WRITE" ], "revoke": [] } } }`; const response = await fetch('https://ditto.eclipseprojects.io/api/2/policies/string/entries/string', { method: 'PUT', headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "subjects": { "{{ request:subjectId }}": { "type": "the creator" } }, "resources": { "policy:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "thing:/": { "grant": [ "READ", "WRITE" ], "revoke": [] }, "message:/": { "grant": [ "READ", "WRITE" ], "revoke": [] } } }''' response = requests.put( 'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string', data=body.encode('utf-8'), headers={ 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ```