Native lock code functionality

[raman325]

CC @AlCalzone @marcelveldt for input from a Z-Wave/Matter perspective

Background

The lock platform natively allows users to control the lock state of a lock, but it is not possible, at least natively, to manage codes for the lock. While not all locks have this functionality, many integrations/protocols support this, including zwave_js, zigbee, matter, and proprietary WiFi/BLE locks.

Today, integrations are forced to handle lock code management on their own. For zwave_js, there are zwave_js specific services to manage user codes, but there isn't a native UI that makes them easily manageable. As a result, there are integrations like https://github.com/FutureTense/keymaster which hack together a solution using a combination of the HA packages functionality, input helpers, and automations. In addition to generating a lot of artifacts which pollute a user's instance, the UI that gets created is not optimized for the use case and is quite complex given what it's trying to accomplish.

Purpose

The purpose of the initial proposal is to come to a consensus that a new entity platform is needed to support codes. There are a lot of details to iron out about this platform, and we can discuss that as a follow up, but I first want to come to consensus that this is needed and that we can't use what we already have.

Considerations

• Not all locks support codes
• Codes can be of variable length and an integration may need to enforce some rules on them
• While most locks with codes that I have seen use PIN numbers, we should consider a scenario where alphanumeric characters may want to be used
• We may also want to consider locks that don't have user defined codes but user configurable identifiers such as an RFID tag for this use case.
• There may be additional metadata about a code that can't be stored in the lock itself that integrations would want to keep track of, such as assigning a name/person entity to a code.

Options

Option 1: Leave things as is and let integrations create their own solutions

We could choose to do nothing and to continue to let each integration figure this out. Integrations can provide a lot of this functionality through services, and when entity services support responses, most if not all of it will be available.

Pros:

• No additional work required in the core or frontend
• Users who already have a solution in place can continue to use that solution

Cons:

• Every integration would have to build its own UI for managing codes if that was desired/needed
• It would be difficult for users to mix and match locks from different integrations because their automations would have to be integrations specific

Considerations:

• We would have a difficult time obtaining Z-Wave certification for HA. See User Code CC support zwave-js/backlog#25 for specific requirements.
• This may also affect a future Matter certification although I am less knowledgeable about what's required there.

Option 2: Use existing HA constructs

Now that most of the input helpers have corresponding entity platforms, integrations could cobble together their own collection of entities that can be used to manage user codes. text entities could be used to view and set codes (and names), and a switch could be exposed to allow codes to be enabled/disabled.

Pros:

• No additional work required in the core or frontend
• Platforms like the text entity already support regex validation and could be used to enforce requirements on the code
• Integrations can add support for this today.

Cons:

• My Z-Wave lock supports up to 30 user codes. If we were to create three entities for every code (text entity for code, text entity for a name, and a switch entity for enabled state), that would result in 90 entities for my one lock. In addition to being a lot of entities, users would have to construct a UI for user code management themselves, and that UI would not be well optimized for the use case.
• Automations would still likely have to be integration specific because every integration could choose to implement this slightly differently
• A UI would not be optimized for this particular use case and users would be required to build their own UI, or integraitons would have to build their own UI.

Considerations:

• We'd have to evaluate whether this would be sufficient for Z-Wave certification. I think we could make it work but it would not be as clean as I think we'd prefer it to be.

Option 3: Establish a new entity type for codes

Pros:

• We could standardize how codes are managed across integrations
• We could create an optimized UI for user code management
• We could reuse some of the techniques we've used elsewhere (like regex validation in the text entity) to provide the needed capabilities while giving integration owners a consistent pattern to follow.
• We could explicitly look at the Z-Wave certification requirements (and Matter certification requirements if they exist) and ensure that we are checking all of the boxes in terms of functionality.

Cons:

• This would require significant work in both the core and the frontend
• There's a risk that we don't foresee all the necessary use cases and integrations will inevitably have to build their own custom solutions for something we are trying to support natively

Considerations:

• We probably want a way to tie this new entity type back to the lock entity. While they would all be tied together through the device_registry, I don't think we can assume that a single device is a single lock, although I don't have any good examples to support that theory.

Recommendation

I recommend that we go with option 3 but spend some time researching what the requirements are that we need to support before creating an in depth proposal. Even if we were able to get certified using option 1 or 2, the user experience is not great (keymaster is a good way to "test" how option 1 or 2 might look like from a user perspective, and while some of the functionality would definitely be eliminated if integrations supported these things natively, my experience has shown that it is suboptimal)

[dknowles2]

I'm not sure there's a meaningful distinction between Option 1 & Option 2. If integrations are creating their own solutions, they are inherently using existing HA constructs. But I agree with your analysis of the cons here, and that's essentially why I didn't implement this for the Schlage integration: there's not really a clean way to model this in HA.

Let's consider the features we would want a lock code to have:

• name - Handled by a base entity type
• code - A (semi secret) value that is associated with a particular entity
• enabled - A toggle for whether the code can be used

Looking at the zwave certification list, I also see:

• admin_code - Whether a code has administrative powers
• keypad_mode - (I'm not sure I understand what this means?)

Some other interesting things to note:

• The access code itself should not be visible by default in the UI. If you have administrative access to a lock (e.g. you have access to HA, which has full control over the lock anyway) then you should be able to read the code, but it shouldn't be immediately shown.
• Administrative attributes & Keypad mode are both optional attributes that not every code would support. I don't think those have analogous settings in Schlage, for example.
• When changing a code (assuming the input is a numeric keypad on the screen) you would want the user to enter the value twice to make sure it's correct. Alternatively, since HA is a rich UI, we could provide a free-form text box.
• Showing a list of lock codes for a lock likely warrants its own section in the UI. Having them intertwined with other entities could be confusing, and you would instead expect them to be grouped together.
• Adding a new access code from the HA UI should be possible, but I'm not sure where that would go. Is there a similar paradigm with another entity type? I'm not sure there is...
• Similarly, you need to be able to remove an access code.

There are probably other things worth considering, but that's what's top-of-mind for me. ;)

[raman325]

Your point about options 1 and 2 being the same is valid, and if anything, that demonstrates why leaving it up to integrations is going to lead to a fragmented experience.

Thanks for those additional thoughts. I need to look into admin code and keypad mode more because I'm not familiar with them

[AlCalzone]

• enabled - A toggle for whether the code can be used

Z-Wave goes even further and has different "user ID statuses", which define how a code slot behaves. I'll just share the table instead of reiterating it:

[allenporter]

I think that this is a broader problem where option 3 directionally feels right. Alarm control panels also deal with codes.

I'm not sure if its an entity platform or something else like application credentials that can be used by integrations? Maybe thinking more about the access patterns for alarm control panels and locks would help? I may be focused on the "local code" use case which is perhaps different since i'm thinking about how manual or template alarm could use this for a DIY alarm system.

Future use cases:

• Might want to have the same code for a lock as an alarm control panel or shared across a couple locks.
• Codes may expire. I'd like to give my cat sitter a code that works for this weekend.
• … Or have a schedule. I'd like to give a guest access between 2-3pm on Wednesdays

[jvmahon]

It seems this may also be considered at a higher level of abstraction. Rather than a entity for input of lock codes, I'd suggest a more generalized "table" input entity may be better (or, at least, for the underlying foundation to build this on). There are several input items that are tables in form - for example, Lock codes (rows with User ID, Status, Type, PINCode columns), Groups (rows with IDs, Groups Names, Members), Scenes (rows with ID, Name, Members), Schedules, etc.

Perhaps the starting place for something like this is a concept like this flex-table-card lovelace https://github.com/custom-cards/flex-table-card?tab=readme-ov-file, and see example images: https://github.com/custom-cards/flex-table-card/blob/master/images/MultiExample.png, but extended into a reusable Entity that could appear on a device's page for lock codes, Groups, Scenes, or other data in 2D table form.

Then build from this 2D Table Input Entity to the more purpose-specific integration implementation.

[Hedda]

FYI, there is a feature request with related discussions from an end-user point-of-view in the Home Assistant's community forum here:

• https://community.home-assistant.io/t/lock-codes-user-management-unified-inc-users-pin-codes-for-code-locks-centalized-tracking-which-users-locked-unlocked-a-lock-and-when-how-was-locking-done-manual-from-inside-outside-keypad-integration-service-or-home-assistant-companion-etc/771302

The lock platform natively allows users to control the lock state of a lock, but it is not possible, at least natively, to manage codes for the lock. While not all locks have this functionality, many integrations/protocols support this, including zwave_js, zigbee, matter, and proprietary WiFi/BLE locks.

Can I suggest that you might also want to get zha/zigpy developers involved early for also looking at it from the Zigbee (ZHA) perspective?

• https://www.home-assistant.io/integrations/zha
  • https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha
    • https://github.com/zigpy/zha
      • https://github.com/zigpy/zha-device-handlers
        • https://zigbeealliance.org/wp-content/uploads/2021/10/07-5123-08-Zigbee-Cluster-Library.pdf

[ReneNulschDE]

Whenever this topic gets focus, it would be great to add the option that a code is not required when the lock request is executed. This feature is available for the alarm_control_panel (aka code_arm_required) but not for locks.

Use case:

• Cars can be locked without a pin

[Hedda]

As a workaround you could maybe workaround that for Z-Wave if this PR was added -> home-assistant/core#119714

[jvmahon]

starting with a more basic concept, lock code management is really management of a table of rows / columns with each row representing the data for a different user, each column being one of the characteristics of the PIN for that row, and having the ability to create, delete, and update rows.

Lots of data types could benefit from a generic input entity that could be arranged in rows / columns (lock PINs, bindings, groups, etc.) with create, delete, update row capabilities.

The first question I had was whether there was anything like that already in HomeAssistant/Core. I think there is. If you think about it, the calendar entity, https://developers.home-assistant.io/docs/core/entity/calendar, is essentially a row-column type input entity, where each date entry is like a row, and the columns are all fixed name and data type (start, end, summary, location, description, etc.). Granted, for the calendar, the UI doesn't use a "row" but the underlying start, end, summary, location, description data can be seen as column entries.

So, perhaps with the calendar entry code as a starting point, someone smarter than me on UI, could change that code such that you could have user-supplied labels and types for the data fields, and a user-supplied number of fields. This would form the basis of a new "core" input type ("data_table"), what could be used for locks, bindings, groups, or anywhere Row/Column type data inputs were needed. In other words, I'm suggesting the architecture update should begin with a more basic building block.

[Hedda]

Wonder if have also got input on the architecture of a native lock code functionality concept from @firstof9 & @FutureTense of keymaster?

• https://github.com/FutureTense/keymaster/

  • https://community.home-assistant.io/t/keymaster-z-wave-lock-manager-and-scheduler/166419

[firstof9]

I'm not sure how this would get added into the core.
Perhaps a way to assign a code to a person entity or a way to associate it to a person?

[paolotremadio]

I’d suggest to look into how Matter clusters are structured. They’ve done a fairly decent job. Manufactures are likely to follow the same schema moving forward

[Hedda]

I’d suggest to look into how Matter clusters are structured. They’ve done a fairly decent job. Manufactures are likely to follow the same schema moving forward

Also note that while the implementations of most Zigbee devices are usually seen as "the wild west" compared to Z-Wave, the Zigbee Pro applications and the Matter Data Model schema does at least use the same underlying ZCL (Zigbee Cluster Library), with both those utilizing the ZCL specifications that is being developed by the Connectivity Standards Alliance (which was formelly known as the Zigbee Alliance). Other have before suggested to build door lock device template using the Door Lock cluster based on ZCL check out Project CHIP's ZAP (ZCL Advanced Platform) tool:

• https://github.com/project-chip/zap

  • https://docs.silabs.com/zap-tool/1.1.0/zap-start/

[jvmahon]

I’d suggest to look into how Matter clusters are structured. They’ve done a fairly decent job. Manufactures are likely to follow the same schema moving forward

Another area where Matter should be considered in the model is the multi-admin feature. Because a device can be connected to multiple controller types / fabrics, the code change can come "from anywhere" - i.e., it does not necessarily originate within Home Assistant but cam come from a foreign controller.

For a Matter device, you'd need to read the code tables from each lock at each startup - because another controller could have changed the code at any time, you can't rely on stored data. The Matter lock entity also needs to subscribe to lock events, including the code add / change / delete events.

[AlCalzone]

For Z-Wave this concern is handled through notifications. The specs about when to report what to the lifeline are extensive.

[Hedda]

For reference also see this new pull request by Ahbrown41 for adding a initial Matter lock manager with Code/User Management to Home Assistant’s core:

• Add Matter lock user and credential management services core#161936

Which in turn is a stripped down PR based on his work on a much larger backend implementation in a seperate PR that now been closed:

• Matter Lock Manager Backend core#159619

as well as a matching pull request with a Matter Lock Manager UI for Home Assistant’s frontend:

• Matter lock manager frontend#28672

This was also discussion under feature requests discussion section here:

• https://github.com/orgs/home-assistant/discussions/551

this is plumbing work to allow other things to build on top of it. I had a fully working backend with an API, actions and events along with a fully functioning UI, I was asked to strip out all extra stuff which I did and so this is now completely bare bones. I can do more, I could come up with an abstraction layer but it would sit on these bones anyway.

All I want is Matter pin/user management so I do not have to use another tool, it has been years that I have been waiting for native not external support for pin/user mangement so I took it on myself to do it. The UI I had was comprehensive and tested and clould use single user, scheduled and perminant users.

I can do changes to the global lock object but it is very unlikely this PR would get approved with that change from what I see

I agree it will probably be a tougher sell to make changes to the core Lock object model, but I wanted to note it down to memorialize.

I was also tired of waiting for native pin management and provided a scripted approach https://github.com/orgs/home-assistant/discussions/551#discussioncomment-15471048 to the community a few weeks ago, completely unaware of this epic and work.

@Ahbrown41 I understand that the home-assistant/core#161936 pull request "only" adds some parts of underlying work that is needed to enable other things to build on top of this to allow usercode management for locks. However I still think that since this could direcctly determine or have indirect consequences on future architecture that at least the concepts and principles here in #1000 and should also be explained / discussed in this related architecture discussion -> #1000 as that way it will allow others in the community to see, give feedback and post their ideas about it too:

• Native lock code functionality #1000

From what I have seen in the past not even underlying work like this that will affect cross-platform or cross-domain features will normally not be accepted before overall architecture changes and future goals for it has been discussed there under architecture discussion and approved + recorded as an Architecture Decision Record that describes the goal and the process(es) to get to set goal which is stored in the ADR folder in that architecture repository.

As I understand it the point with those architecture discussions and ADs is to avoid developers like yourself working on something that have to be scrapped or getting PRs rejected because it is seen as a workaround and not aimed towards the solution that was set in the Architecture Decision Record and decided through such architecture discussions. And while it could be seen as a downside with forcing architecture discussions and recording ADRs however the consequence it that it "introduces an additional burden on core project maintainers to diligently follow architecture discussions and record the results in this repo as an ADR").

Again, recommend that the overall architecture discussion about this is moved to that existing discussion about native lock functionality -> #1000 or alternativly that you open a new discussion there (like example about "native usercode management functionality" for architecture discussions and recording via ADRs, otherwise there is probaly a chance that @mkerstner or @tailg8nj and others who might have input on the architecture for it miss this discussion -> https://github.com/home-assistant/architecture/discussions/new/choose

[Hedda]

By the way, also see related roadmap discussion which raised by @mkerstner which discusses benefits of having a unified code management system(s) and a shared credential UI for all integrations (i.e. a protocol-agnostic foundation that suits a range of protocols) that includes codes for both locks and alarm control panels:

• https://github.com/home-assistant/roadmap/issues/8

and the related epic tracker for protocol-agnostic credential management:

• Evaluate a stable foundation for protocol-agnostic credential management epics#28

That highlights that the long term goal for usercode management of users and PIN-codes for each user should really take usercodes for both lock and alarm control panel into consideration here. With a long term vision to aim for a more coherent credential management across supported protocols/devices for users and their usercodes.

This roadmap entry also specifically mentions "Aliro" which is a new/upcoming official open standard for making digital door keys work across different manufacturers and platforms that is aiming for official launch by Connectivity Standards Alliance the sometime during 2026 (with the specifications for Aliro 1.0 currently being in the final review phase before it is formally ratified as an official standard from the CSA):

• https://csa-iot.org/all-solutions/aliro/

Aliro is a "standardized communication protocol between access readers and user devices, providing a convenient and consistent experience" and it can be described as “Matter for digital door keys” as it is all about interoperability between digital keys and locks.

• https://matter-smarthome.de/en/know-how/what-is-the-aliro-standard/

"It is important to distinguish between Aliro and Matter. Both are managed by the same organization (CSA), but they have different jobs. Matter is, in a sense, the caretaker. It takes care of administration and control: “Door closed?”, “Lock the door at 10 p.m.”, “Battery level low.” For this purpose, Matter communicates via an existing IP network (Wi-Fi or Thread). The Aliro standard replaces the doorman. It checks access authorization: “Is this person allowed in?” This communication takes place directly between the phone and the lock (point-to-point), without Wi-Fi or a hub."

[Hedda]

FYI, for reference, Home Assistant 2026.4 release (currently in Beta) adds an initial Matter lock user and credential management services feature which allows you to manage your lock users and PIN codes directly from the Home Assistant UI if you have have a Matter-compatible smart lock. This change adds the ability to manage Matter lock codes from within Home Assistant via the new "Manage Lock" menu added to Home Assistant's frontend (UI):

• https://rc.home-assistant.io/blog/2026/03/25/release-20264/#matter-lock-manager

  • https://home-assistant.io/blog/2026/03/25/release-20264/#matter-lock-manager

    

• On the device page of your Matter lock, you’ll find a new "Manage lock" option. It opens a dialog where you can see all configured users, add new ones, edit existing ones, or remove them. When adding a new user, you give them a name, set a PIN code, and choose an access type: full access (can lock and unlock anytime) or one-time access (the code works once and is then automatically deleted by the lock).

  

• Under the hood, this is powered by a new set of Matter lock actions that are also available for use in your automations and scripts. You can, for example, create a one-time PIN code for a guest and send it in a notification, all from an automation! The available actions include creating and removing users, setting and clearing credentials (like PIN codes and RFID tags), and querying the lock’s capabilities.

  

This awesome contribution to Home Assistant's Matter inteation was initiated by @Ahbrown41 See related frontend and backend pull reqeusts:

• Add Matter lock user and credential management services core#161936

  The new capability supports the adding and removing of both permanent and single use users for now (Scheduling etc can come later). This new ability builds on recent changes to the backend dev branch that implement the backend matter functionality for managing lock codes etc.

• Matter lock manager frontend#28672

  Adds 7 entity services for Matter lock user and credential management, aligned with the Matter DoorLock cluster specification (Application Cluster Spec, Chapter 5.2). These services expose the DoorLock cluster's user and credential commands as Home Assistant actions, accessible from automations, scripts, and Developer Tools.

This concept initially started as a discussion about PIN management for Matter Door Locks under the feature requests discussion section here:

• https://github.com/orgs/home-assistant/discussions/551

this is plumbing work to allow other things to build on top of it. I had a fully working backend with an API, actions and events along with a fully functioning UI, I was asked to strip out all extra stuff which I did and so this is now completely bare bones. I can do more, I could come up with an abstraction layer but it would sit on these bones anyway.

All I want is Matter pin/user management so I do not have to use another tool, it has been years that I have been waiting for native not external support for pin/user mangement so I took it on myself to do it. The UI I had was comprehensive and tested and clould use single user, scheduled and perminant users.

I can do changes to the global lock object but it is very unlikely this PR would get approved with that change from what I see

I agree it will probably be a tougher sell to make changes to the core Lock object model, but I wanted to note it down to memorialize.

I was also tired of waiting for native pin management and provided a scripted approach https://github.com/orgs/home-assistant/discussions/551#discussioncomment-15471048 to the community a few weeks ago, completely unaware of this epic and work.

PS: I understand that that initial Matter lock manager "only" adds some parts of underlying work that is needed to enable other enhanced lock management features s to build on top of this to allow usercode management of doorlocks (i.e. managing user permissions for locks and PIN-usercodes). However I still think that implementing this bacis functionality for Z-Wave and Zigbee lock credentials and lock PIN-codes for devices via the Z-Wave JS integration and the ZHA integrations for Home Assistant could direcctly determine or have indirect influence on future architecture that at least the extended and more advanced cross-platform concepts and principles discussed in this related feature request discussion:

• https://github.com/orgs/home-assistant/discussions/2555

Note! Again, please also see related roadmap discussion which raised by @mkerstner which discusses longterm benefits of having a unified code management system(s) and a shared credential UI for all integrations (i.e. a cross-platform and protocol-agnostic global foundation that suits a range of protocols) that includes codes for both locks and alarm control panels:

• https://github.com/home-assistant/roadmap/issues/8

and the related epic tracker for protocol-agnostic credential management:

• Evaluate a stable foundation for protocol-agnostic credential management epics#28

By the way, when implementated globally for locks then perhaps same or similar solution could also be done for alarm control panel?

[Hedda]

Note! Again, please also see related roadmap discussion which raised by @mkerstner which discusses longterm benefits of having a unified code management system(s) and a shared credential UI for all integrations (i.e. a cross-platform and protocol-agnostic global foundation that suits a range of protocols) that includes codes for both locks and alarm control panels::

• https://github.com/home-assistant/roadmap/issues/8

FYI, apparently a pm from Open Home Foundation noted this is wanted and added credential management for Z-Wave locks to a roadmap:

• Credential management for Z-Wave locks OpenHomeFoundation/roadmap#70

(Note that just because they added it to their roadmap does not mean that someone is actually working on it or planning to work on it yet).

[Hedda]

FYI, for reference, @mkerstner mentioned in OpenHomeFoundation/roadmap#70 that he has written down some notes on a first scope for the way forward for credential management (which includes locks and alarm control panels) which he outlined in this initial document:

• https://docs.google.com/document/d/1kHqgRYzKV_FWDjPqZkr_D4B4jG2tf6nGhHUH0W7nBM4/edit?pli=1&tab=t.0#heading=h.3dxiy9s5z2m6

  "At the heart, we aim to fully support door locks / keypads / alarm panels (or “openings” in general) natively from within HA without requiring a 3rd party ecosystem/app and independent of the protocol used. This includes credential management but also of course options to automate upon (scheduling, etc.). The reality as of now is that we are missing some basic functionality for:

  • managing codes (PIN, credentials)
  • RFID tags / fingerprints
  • event logs

  Or at least only have partial support on selected protocols (Z-wave, Zigbee) and rely on using community provided apps and configurations, which generally don’t seem to be that user-friendly for the broader community (e.g. KeyMaster and the amount of entities created).

  From a user’s perspective, coming from ecosystem apps like SmartThings CRUD actions on codes and at least basic audit logs (e.g. who unlocked the door) are mandatory. Going further, extended base use cases like managing multiple users and temporary codes or scheduling need to be included in a sensible baseline as well..

  All major protocol standards like Matter do support this (e.g. Door Lock User / Door Lock Credential clusters for Matter) so implementing it should be possible in HA as well."

Note that the section on "Access Tracking & History" there focus on event logging and actions on events.

[Hedda]

FYI; mkerstner has created a new issue to track a new WIP (work-in-progress) roadmap item to expand on credential management for locks:

• Expand further on credential management OpenHomeFoundation/roadmap#109

For reference, in it he also links to an updated document with his own notes on way forward for credential management in Home Assistant:

• https://docs.google.com/document/d/1kHqgRYzKV_FWDjPqZkr_D4B4jG2tf6nGhHUH0W7nBM4/edit?tab=t.0#heading=h.iup5wfolvtoy

As I understand it, he is now looking for first feedback after the initial release of the Matter lock credentials management in Home Assistant release 2026.3 so do not potentially miss feedback before moving forward with expanding the scope of credential management for locks.