Skip to main content
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 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 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: 
{
  "trusted_metadata": {
    "key1": "value1"
  }
}
Update: 
{
  "trusted_metadata": {
    "key2": "value2"
  }
}
Result: 
{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

​
Example: replacing an existing field

Initial: 
{
  "untrusted_metadata": {
    "key1": "value1"
  }
}
Update: 
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}
Result: 
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}

​
Example: updating a deeply nested field

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"
  }
}

​
Example: deleting a field

Initial: 
{
  "untrusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
Update: 
{
  "untrusted_metadata": {
    "key1": null
  }
}
Result: 
{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}

​
Example: deleting all fields

Initial: 
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
Update: 
{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}
Result: 
{
  "trusted_metadata": {}
}