feat: delete metadata on SetUserMetadata api (#11776)

# Which Problems Are Solved

Currently, to delete metadata a key, callers must use a separate
[DeleteMetadata](https://zitadel.com/docs/reference/api/user/zitadel.user.v2.UserService.DeleteUserMetadata)
API. This increases the complexity on client-side for operations where
metadata need to be synchronized.

# How the Problems Are Solved

Introduce the behavior to
[SetUserMetadata](https://zitadel.com/docs/reference/api/user/zitadel.user.v2.UserService.SetUserMetadata):

When a metadata entry is passed with an empty value ("" / empty bytes):

- If the key exists → delete the key
- If the key does not exist → no-op (idempotent, no error)

# Additional Changes

- Updated [User Metadata
page](https://zitadel.com/docs/guides/manage/customize/user-metadata#manage-user-metadata-through-the-management-api)

# Additional Context

Similar behavior will be applied to
[UpdateUser](https://zitadel.com/docs/reference/api/user/zitadel.user.v2.UserService.UpdateUser)
and
[SetOrganizationMetadata](https://zitadel.com/docs/reference/api/org/zitadel.org.v2.OrganizationService.SetOrganizationMetadata)

Breaking change? 
Currently, sending an empty value returns an error — no client should be
intentionally relying on that error as part of a working workflow. The
change goes from "rejected input" to "accepted input with defined
semantics."

In other words, it relaxes a restriction rather than tightening one.
Existing valid calls continue to work exactly as before. The only
scenario where it could be "breaking" is if someone explicitly depends
on the error response for empty values (e.g., using it as a validation
check), which would be unusual.

---------

Co-authored-by: Gayathri Vijayan <[email protected]>
Co-authored-by: Copilot <[email protected]>
This commit is contained in:
Vitor Bari Buccianti
2026-03-06 14:57:52 +01:00
committed by GitHub
co-authored by Gayathri Vijayan Copilot
parent 3443507c20
commit 247e278505
6 changed files with 205 additions and 69 deletions
+15 -1
View File
@@ -74,8 +74,22 @@ func (c *Commands) BulkSetUserMetadata(ctx context.Context, userID, resourceOwne
}
userAgg := UserAggregateFromWriteModel(&setMetadata.WriteModel)
for _, data := range metadatas {
existingValue, keyExists := setMetadata.metadataList[data.Key]
// if value is empty, a metadata remove event has to be pushed
if len(data.Value) == 0 {
// Ignore deletion if key does not exist
if !keyExists {
continue
}
event := user.NewMetadataRemovedEvent(ctx, userAgg, data.Key)
events = append(events, event)
continue
}
// if no change to metadata no event has to be pushed
if existingValue, ok := setMetadata.metadataList[data.Key]; ok && bytes.Equal(existingValue, data.Value) {
if keyExists && bytes.Equal(existingValue, data.Value) {
continue
}
event, err := c.setUserMetadata(ctx, userAgg, data)
+31 -10
View File
@@ -491,7 +491,7 @@ func TestCommandSide_BulkSetUserMetadata(t *testing.T) {
},
},
{
name: "invalid metadata, pre condition error",
name: "empty metadata value, ok",
fields: fields{
eventstore: expectEventstore(
expectFilter(
@@ -523,7 +523,9 @@ func TestCommandSide_BulkSetUserMetadata(t *testing.T) {
},
},
res: res{
err: zerrors.IsErrorInvalidArgument,
want: &domain.ObjectDetails{
ResourceOwner: "org1",
},
},
},
{
@@ -584,17 +586,34 @@ func TestCommandSide_BulkSetUserMetadata(t *testing.T) {
),
),
),
expectFilter(),
expectFilter(
eventFromEventPusher(
user.NewMetadataSetEvent(context.Background(),
&user.NewAggregate("user1", "org1").Aggregate,
"key1",
[]byte("value1"),
)),
eventFromEventPusher(
user.NewMetadataSetEvent(context.Background(),
&user.NewAggregate("user1", "org1").Aggregate,
"key2",
[]byte("value2"),
)),
),
expectPush(
user.NewMetadataSetEvent(context.Background(),
user.NewMetadataRemovedEvent(context.Background(),
&user.NewAggregate("user1", "org1").Aggregate,
"key",
[]byte("value"),
"key1",
),
user.NewMetadataSetEvent(context.Background(),
&user.NewAggregate("user1", "org1").Aggregate,
"key1",
[]byte("value1"),
"key2",
[]byte("update"),
),
user.NewMetadataSetEvent(context.Background(),
&user.NewAggregate("user1", "org1").Aggregate,
"key3",
[]byte("add"),
),
),
),
@@ -604,8 +623,10 @@ func TestCommandSide_BulkSetUserMetadata(t *testing.T) {
orgID: "org1",
userID: "user1",
metadataList: []*domain.Metadata{
{Key: "key", Value: []byte("value")},
{Key: "key1", Value: []byte("value1")},
{Key: "key1"}, // delete
{Key: "key2", Value: []byte("update")},
{Key: "key3", Value: []byte("add")},
{Key: "key4"}, // ignore
},
},
res: res{