Upsert Access Control Rule

POST /access-control-rules

Upsert an access control rule.

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

Required scope

Any authenticated access token

Header parameters

If-Matchstring

Optional quoted etag of the rule as last read (its `etag` field). When present the upsert applies only if it still matches the rule's current etag, otherwise 412 PRECONDITION_FAILED; `*` requires the rule to exist. Omitted, the upsert is unconditional.

minLength: 1

Request body

Fields

idstring

The ID of the access control rule to upsert on.

effectstringRequired

Allowed values: ALLOW, DENY.

operationstringRequired

The operation to grant access to. This could be a read, write, delete, etc. Please see the access controls list specification for all operations and their descriptions.

resourcestringRequired

The resource to grant access to. This could be an endpoint, a flow, a secret, etc. You can define this as either a class of resources, or a specific resource. Examples: - port1/principals/alice/endpoints/thermostat-zero grants access to that thermostat - port1/principals/alice/flows/* grants access to all flows owned by alice

identitystringRequired

The identity to grant access to. This could be a user, a role, a group, etc. You can define this as either a class of identities, or a specific identity. Examples: - port1/principals/bob grants access to bob - * just grants access to all identities

conditionsarray<AccessControlRuleCondition>

Conditions on the operation context that must all match for the rule to apply. Omitting conditions means the rule has none.

reasonstring

Optional operator-supplied reason recorded in the audit log for this change.

maxLength: 500

Returns

200

Access control rule upserted successfully

Fields

idstringRequired: The ID of the access control rule

Response headers

ETagstring: Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.

Errors

400

Invalid request payload

Check the request fields and any validation details, then correct the payload.

412 PRECONDITION_FAILED

The If-Match etag does not match the current access control rule; re-read the rule and retry

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.