Metadata Best Practices
Metadata field names
Metadata field names must not contain a dot or ellipsis. For example, using this field name returns a Bad Request (400) error:
One way of handling this limitation is to nest attributes:{ "preference.color": "pink" }
Was this helpful?/Alternately, you can use any delimiter that is not{ "preference": { "color": "pink" } }
Was this helpful?/.
or$
with the exception that you can use the.
delimiter in data values like this:{ "preference": "light.blue" }
Was this helpful?/
Do not use dynamic field names. Dynamic fields reduce indexing efficiency and cause degradation in search queries. A static schema is easier to search, manipulate, and work with. For example, instead of using this structure:
Use this:"participants": { "Alice" : { "role": "sender" }, "Bob" : { "role": "receiver" } }
Was this helpful?/"participants": [ { "name": "Alice", "role": "sender" }, { "name" : "Bob", "role": "receiver" } ]
Was this helpful?/
Metadata data types
Use a consistent data type each time you create or update a given metadata field. For example, if you use user.user_metadata.age = "23"
for one user and user.user_metadata.age = 23
for another user, it will cause issues when retrieving the data.
Metadata storage and size limits
Both
app_metadata
anduser_metadata
are together limited to a size of 16 MB total per user. Metadata storage is not designed to be a general purpose data store, and you should still use your own external storage facility when possible. When using Rules and/or the Dashboard, your metadata limits may be lower.When setting the
user_metadata
field using the Authentication API Signup endpoint, you are limited to a maximum of 10String
fields and 500 characters. For an example of working with metadata during a custom signup process, see Custom Signup > Using the API.
Customize emails with metadata
Store any information that you want to use to customize Auth0 emails in metadata. Use user_metadata.lang
if the user is allowed to change the field's value, such as information used to determine the language for an email. See Customize Email Templates for details.
App metadata restrictions
User credentials such as access tokens, refresh tokens, and additional passwords should not be stored in app_metadata
, as these will be visible to any Dashboard administrator.
The app_metadata
field should not contain any of these properties:
__tenant
_id
blocked
clientID
created_at
email_verified
email
globalClientID
global_client_id
identities
lastIP
lastLogin
loginsCount
metadata
multifactor_last_modified
multifactor
updated_at
user_id