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

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

Stytch Users contain two types of metadata - trusted_metadata and untrusted_metadata.

Direct API integrations can read and write to both trusted_metadata and untrusted_metadata.

Frontend SDK integrations can read and write to untrusted_metadata, but only read trusted_metadata.

Secure fields, such as a User's role, billing_status, or stripe_customer_id should only be stored in trusted_metadata by using a direct API integration. Fields that a User 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 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.

Initial:

{
  "trusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "trusted_metadata": {
    "key2": "value2"
  }
}

Result:

{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Initial:

{
  "untrusted_metadata": {
    "key1": "value1"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Result:

{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

Initial:

{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}

Update:

{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }]
  }
}

Result:

{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }],
    "other_key": "other_value"
  }
}

Initial:

{
  "untrusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}

Update:

{
  "untrusted_metadata": {
    "key1": null
  }
}

Result:

{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}

Initial:

{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}

Update:

{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}

Result:

{
  "trusted_metadata": {}
}