AccessControl Cluster

Cluster ID: 0x001F  |  Endpoint: Fixed on Endpoint 0 (root endpoint)

AccessControl is the permission management hub of a Matter device -- it determines "who" can perform "what operations" on "which resources". Every Matter device must implement this Cluster on Endpoint 0. It has no commands; all configuration is done by directly writing to the ACL attribute.

Core Concept

ACLs are isolated by Fabric -- each Fabric (control domain) maintains an independent list of access control entries without interfering with each other. After Commissioning is complete, the device automatically creates an Administer privilege entry for the Commissioner, which is the foundation for all subsequent operations. If the ACL is misconfigured, the device may become "unreachable" and can only be recovered via factory reset.

Attributes

The attributes of the AccessControl Cluster are divided into two groups: ACL Data (read/write permission configuration) and Capacity Limits (read-only device capability limits). Click on an attribute ID in the summary table below to jump to its detailed description.

ID Name Type Group Description
0x0000 ACL list<AccessControlEntryStruct> ACL Data Access control entry list (core attribute)
0x0001 Extension list<AccessControlExtensionStruct> ACL Data Vendor-specific extension data
0x0002 SubjectsPerAccessControlEntry uint16 Capacity Limits Maximum number of Subjects per ACL entry
0x0003 TargetsPerAccessControlEntry uint16 Capacity Limits Maximum number of Targets per ACL entry
0x0004 AccessControlEntriesPerFabric uint16 Capacity Limits Maximum number of ACL entries per Fabric
0x0005 CommissioningARL list<CommissioningAccessRestrictionEntryStruct> Access Restrictions Access restriction list during Commissioning phase
0x0006 ARL list<AccessRestrictionEntryStruct> Access Restrictions Runtime access restriction list

ACL Data (0x0000, 0x0001)

Access control entries and extension data -- the core writable attributes of AccessControl.

ID Name Type Description
0x0000 ACL (Access Control List) list<AccessControlEntryStruct> The device's access control entry list. Each entry defines a "who can do what" rule. Isolated by Fabric -- each Fabric can only read and write its own entries. Writing requires a full replacement (incremental modification of individual entries is not supported) and requires Administer privilege. See AccessControlEntryStruct for struct details
0x0001 Extension (Extension Data) list<AccessControlExtensionStruct> Vendor-specific permission extensions. Each entry contains TLV-encoded data of up to 128 bytes. Standard Matter implementations typically do not use this field. Requires the EXTS feature. Writing requires Administer privilege
Important Notes on Writing ACL

Writing ACL is a full replacement operation -- you must write the complete entry list at once; you cannot modify just one entry. If the newly written list does not include your own Administer entry, you will permanently lose administrative access to the device, and the only recovery is a factory reset. It is recommended to read the current ACL first, modify it, then write the entire list back.

↑ Back to Attributes

Capacity Limits (0x0002 ~ 0x0004)

Read-only attributes that describe the device's capacity limits for ACL entries. Read these values before writing ACL to avoid exceeding the device's capabilities.

ID Name Type Description
0x0002 SubjectsPerAccessControlEntry uint16 Maximum length of the subjects list in a single ACL entry. Minimum value is 4
0x0003 TargetsPerAccessControlEntry uint16 Maximum length of the targets list in a single ACL entry. Minimum value is 3
0x0004 AccessControlEntriesPerFabric uint16 Maximum total number of ACL entries a Fabric can have. Minimum value is 4 (enough for at least one administrator entry and a few user entries)
Typical Device Capacity

Typical values for most devices: SubjectsPerAccessControlEntry = 4, TargetsPerAccessControlEntry = 3, AccessControlEntriesPerFabric = 4. Resource-constrained devices (such as battery-powered sensors) may have smaller values. Always read these three values before planning during development.

↑ Back to Attributes

Access Restrictions (0x0005, 0x0006) — MNGD Feature

The Access Restriction List (ARL) is an advanced feature introduced by the MNGD (Managed Device) feature, allowing device manufacturers to restrict access to certain resources even if the ACL permits it. Most consumer devices do not implement this feature.

ID Name Type Description
0x0005 CommissioningARL list Access restrictions during the Commissioning phase. The device informs the Commissioner which resources are restricted during commissioning. Requires the MNGD feature
0x0006 ARL list Runtime access restriction list. Even if the ACL grants permission, resources listed in the ARL remain inaccessible. Requires the MNGD feature

↑ Back to Attributes

Struct Definitions

AccessControlEntryStruct — Access Control Entry

The core data structure of ACL. Each record defines the privilege level that a set of subjects (who) have on a set of targets (which resources).

Field Type Description
Privilege AccessControlEntryPrivilegeEnum Granted privilege level (View / Operate / Manage / Administer)
AuthMode AccessControlEntryAuthModeEnum Authentication mode (PASE / CASE / Group)
Subjects list<subject-id> / null List of subjects allowed to access (Node ID or Group ID). null means all Nodes within the same Fabric are allowed access
Targets list<AccessControlTargetStruct> / null Scope of allowed access targets. null means all Endpoints and Clusters on the device are accessible
FabricIndex fabric-idx Fabric index this entry belongs to (automatically populated by the device; does not need to be specified manually)
The Meaning of null for Subjects and Targets

null in ACL means "no restriction", not "deny". Subjects = null means all Nodes within the same Fabric match; Targets = null means all Endpoints and Clusters on the device are in scope. The default administrator entry typically sets Targets = null because administrators need access to everything.

AccessControlTargetStruct — Access Target

Defines the specific resource scope an ACL entry allows access to. At least one of the three fields must be specified; unspecified fields mean no restriction.

Field Type Description
Cluster cluster-id / null Restrict to a specific Cluster. null = no Cluster restriction
Endpoint endpoint-no / null Restrict to a specific Endpoint. null = no Endpoint restriction
DeviceType devtype-id / null Restrict to a specific device type. null = no device type restriction
Endpoint and DeviceType Are Mutually Exclusive

Endpoint and DeviceType cannot be specified simultaneously -- either match precisely by Endpoint number, or match broadly by device type. If both are set, the device will reject the entry. The most common approach is to specify only Endpoint.

AccessControlExtensionStruct — Extension Data

A vendor-specific extension structure that requires the EXTS feature to be enabled. Rarely used in standard Matter development.

Field Type Description
Data octstr (max 128 bytes) TLV-encoded extension data, content defined by the vendor
FabricIndex fabric-idx Fabric index this entry belongs to

Enum Types

AccessControlEntryPrivilegeEnum — Privilege Levels

Defines the privilege level granted by an ACL entry. Privileges are inclusive -- higher-level privileges automatically include all capabilities of lower-level privileges. For example, Operate includes the capabilities of View, and Administer includes all capabilities.

1
View Read-only privilege -- can read attributes and subscribe to events, but cannot perform any write operations or commands
2
ProxyView Proxy read-only -- similar to View, used for Proxy Node scenarios (rarely used)
3
Operate Operate privilege -- can read attributes + invoke commands (everyday operations like turning on lights, unlocking doors). The most commonly used user privilege
4
Manage Manage privilege -- can operate + write configuration attributes (modify device name, set power-on behavior, etc.)
5
Administer Highest privilege -- can manage + modify ACL itself + perform Commissioning-related operations. Intended for controllers/Hubs only
Privilege Inheritance

Administer ⊃ Manage ⊃ Operate ⊃ View. After assigning Operate privilege to a user, they automatically have View capability, so there is no need to add a separate View ACL entry.

AccessControlEntryAuthModeEnum — Authentication Mode

Specifies the authentication mode that an ACL entry matches. Different authentication modes determine the meaning of the IDs in the Subjects field.

1
PASE Passcode authentication -- used only during the Commissioning phase; automatically expires after commissioning is complete. No manual configuration needed
2
CASE Certificate authentication -- the most commonly used method, based on certificate-backed point-to-point secure communication. Subjects field contains Node IDs
3
Group Group authentication -- used for Group messages (e.g. controlling a group of lights simultaneously). Subjects field contains Group IDs

Events

The AccessControl Cluster records ACL change history through events. Each time the ACL or Extension attribute is written, the device generates a corresponding event. These events are important for security auditing and troubleshooting.

ID Name Priority Description
0x00 AccessControlEntryChanged Info An ACL entry has changed (added, modified, or removed). Event data includes the change type (Changed/Added/Removed), the latest entry content, the operator's Node ID, and the Fabric index
0x01 AccessControlExtensionChanged Info Extension data has changed. Structure is similar to the previous event, recording additions, deletions, and modifications to extension data. Requires the EXTS feature
0x02 FabricRestrictionReviewUpdate Info Fabric access restriction review update. Triggered when ARL rules change. Requires the MNGD feature
Audit Recommendation

In production environments, it is recommended to subscribe to the AccessControlEntryChanged event. If someone accidentally modifies the ACL (e.g. accidentally deletes the administrator entry), the event log can help quickly identify the issue.

Feature Bitmap

The AccessControl Cluster declares the device's supported extension capabilities through the FeatureMap (0xFFFC):

Bit 0
EXTS (Extension) Supports vendor-specific extension data -- when enabled, the Extension (0x0001) attribute can be written
Bit 1
MNGD (Managed Device) Managed device -- supports Access Restriction List (ARL), allowing manufacturers to additionally restrict resource access

Most consumer devices have a FeatureMap of 0x0000 (no features enabled). EXTS is for vendor devices with custom permission requirements, and MNGD is for cloud-platform-managed devices.

Example Data

A typical smart light's AccessControl Cluster read result after Commissioning is complete and a user privilege entry has been added: 

{
  // --- ACL entries (list, independently maintained per Fabric) ---
  "0x0000": [                    // ACL — AccessControlEntryStruct list
    {
      "privilege": 5,            // Administer (administrator)
      "authMode": 2,             // CASE authentication
      "subjects": [112233],      // Bound to Commissioner Node ID
      "targets": null,           // null = can access all Endpoints and Clusters
      "fabricIndex": 1
    },
    {
      "privilege": 3,            // Operate (operate privilege)
      "authMode": 2,             // CASE authentication
      "subjects": null,          // null = all Nodes within the same Fabric
      "targets": [               // Restrict the accessible scope
        { "cluster": null, "endpoint": 1, "deviceType": null }
      ],
      "fabricIndex": 1
    }
  ],

  // --- Capacity Limits ---
  "0x0002": 4,                   // SubjectsPerAccessControlEntry = 4
  "0x0003": 3,                   // TargetsPerAccessControlEntry = 3
  "0x0004": 4                    // AccessControlEntriesPerFabric = 4
}
Developer Tip

The first ACL entry (Privilege = 5, Administer) is automatically created during Commissioning and must never be deleted. When adding user privileges, first read the complete ACL list, append the new entry, then write the entire list back. Note that Extension (0x0001) only exists when the FeatureMap includes the EXTS feature.

Common Scenarios

Scenario 1: Default Administrator ACL (Auto-Generated After Commissioning)

After the device completes Commissioning, it automatically creates an administrator privilege entry for the Commissioner (typically a phone App or Hub):

  • Privilege = Administer (5) -- highest privilege
  • AuthMode = CASE (2) -- certificate-based secure authentication
  • Subjects = [Commissioner's Node ID] -- only this controller
  • Targets = null -- can access everything on the device

This ACL entry is the foundation for all subsequent operations. If it is accidentally deleted, the device can no longer be controlled and can only be recovered via factory reset.

Scenario 2: Add Operate Privilege for a Family Member

The administrator wants a family member (another phone) to be able to control lights and switches, but not modify device configuration:

  1. Read the current ACL list (ensure it contains the administrator entry)
  2. Append a new entry:
    • Privilege = Operate (3)
    • AuthMode = CASE (2)
    • Subjects = [family member's Node ID]
    • Targets = [{ endpoint: 1 }] (only allow operations on the functional Endpoint)
  3. Write the complete list containing both the administrator entry and the new entry to the ACL

After writing, the family member can turn lights on and off, but cannot modify ACL, device name, power-on behavior, or other management-level configurations.

Scenario 3: Set Up Group Multicast Privilege

You need to control a group of lights simultaneously via multicast, e.g. "all living room lights":

  1. First configure the Group Key for each light (via the GroupKeyManagement Cluster)
  2. Add a Group privilege entry in each light's ACL:
    • Privilege = Operate (3)
    • AuthMode = Group (3)
    • Subjects = [Group ID]
    • Targets = [{ endpoint: 1 }]
  3. Then send OnOff commands to the Group, and all lights respond simultaneously

The privilege level in Group mode can only go up to Operate; Manage or Administer operations are not allowed through Group.

Scenario 4: Troubleshoot "Access Denied" Issues

When the device returns an UNSUPPORTED_ACCESS or ACCESS_DENIED error, follow these troubleshooting steps:

  1. Read the device's ACL (0x0000) and verify whether there is an entry matching the current Node
  2. Check whether the matching entry's Privilege is sufficient (e.g. writing attributes requires Manage, modifying ACL requires Administer)
  3. Check whether the AuthMode matches (a CASE-authenticated Node will not match a Group-type ACL entry)
  4. Check whether Targets covers the target Endpoint and Cluster
  5. Verify capacity limits -- read SubjectsPerAccessControlEntry and AccessControlEntriesPerFabric to see if limits are exceeded