> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

Stytch Members may contain `metadata` - arbitrary JSON objects for recording application-specific information.

## Metadata restrictions

* Metadata objects may contain a maximum of 20 top-level keys.
* Metadata objects cannot exceed 4KB in size

## Metadata permissions

Stytch Members contain two types of metadata - `trusted_metadata` and `untrusted_metadata`.

[Direct API](/api-reference/consumer/api)  integrations can read and write to both `trusted_metadata` and `untrusted_metadata`.

[Frontend SDK](/api-reference/consumer/frontend-sdks/react/overview)  integrations can read and write to `untrusted_metadata`, but only read `trusted_metadata`.

Secure fields, such as a Member's `role`, `billing_status`, or `stripe_customer_id` should only be stored in `trusted_metadata` by using a direct API integration. Fields that a Member can be allowed to edit directly - such as `display_theme` or `preferred_locale` may be stored in `untrusted_metadata`.

Do not store any sensitive information (passport numbers, credit card details, etc.) as metadata.

## Metadata update behavior

Metadata update payloads will be merged with the existing metadata at the top level only. Send a top-level value of null to delete an existing field. To delete all metadata from an object, send a top-level value of null for every existing field. Stytch will not merge deeply nested objects or arrays. To add a field to a deeply nested object, or update an array, replace the entire top-level key.

### Example: adding a new field

Initial:

```json theme={null}
{
  "trusted_metadata": {
    "key1": "value1"
  }
}
```

Update:

```json theme={null}
{
  "trusted_metadata": {
    "key2": "value2"
  }
}
```

Result:

```json theme={null}
{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
```

### Example: replacing an existing field

Initial:

```json theme={null}
{
  "untrusted_metadata": {
    "key1": "value1"
  }
}
```

Update:

```json theme={null}
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}
```

Result:

```json theme={null}
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}
```

### Example: updating a deeply nested field

Initial:

```json theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

Update:

```json theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }]
  }
}
```

Result:

```json theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }],
    "other_key": "other_value"
  }
}
```

### Example: deleting a field

Initial:

```json theme={null}
{
  "untrusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

Update:

```json theme={null}
{
  "untrusted_metadata": {
    "key1": null
  }
}
```

Result:

```json theme={null}
{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}
```

### Example: deleting all fields

Initial:

```json theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

Update:

```json theme={null}
{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}
```

Result:

```json theme={null}
{
  "trusted_metadata": {}
}
```