Metadata Field Names and Data Types
Auth0 distinguishes between three types of metadata used to store specific kinds of information.
Metadata Type | Field Name | Description |
---|---|---|
User Information | user_metadata |
Stores user attributes such as preferences that do not impact a user's core functionality. This data can be edited by logged in users if you build a form using the Management API and should not be used as a secure data store. |
Access Information | app_metadata |
Stores information such as permissions, Auth0 plan, and external IDs that can impact user access to features. This data cannot be edited by users and there are restrictions for what can be stored in this field. |
Application Information | client_metadata in the Client object, context.clientMetadata in Rules, and event.client.metadata in post-login Actions. |
Stores information about an application (or client in OIDC OAuth2 terminology). For example, the URL for the application home page (any value that Auth0 doesn’t set in the application settings). |
Metadata field names
Accepted characters
Field names must not contain the .
(dot) or $
(dollar sign) characters.
For example, this is not allowed:
{
"preference.color": "pink"
}
Was this helpful?
But you can expand it like this:
{
"preference": {
"color": "pink"
}
}
Was this helpful?
Dynamic field names
Field names should be static. Dynamic field names reduce indexing efficiency and cause degradation in search queries. A static schema is easier to search, manipulate, and work with.
Instead of doing this:
{
"participants": [
"Alice": {
"role": "sender"
},
"Bob": {
"role": "receiver"
}
]
}
Was this helpful?
Do this:
{
"participants": [
{
"name": "Alice",
"role": "sender"
},
{
"name" : "Bob",
"role": "receiver"
}
]
}
Was this helpful?
Name collision
Avoid using the same name for app_metadata
fields and root profile fields. The app_metadata
field is merged onto the root profile in both Rules and Actions, which may override root profile fields.
For example, if a user has a groups
field present on their root profile (returned from a SAML identity provider) and a groups
field within app_metadata
, their profile might look like this:
{
"user_id": "samlp|example-samlp-connection|username@domain.com",
"groups": [
"external-group-1",
"external-group-2"
],
"app_metadata": {
"groups": [
"internal-group-1",
"internal-group-2"
]
}
}
Was this helpful?
When you read the groups
field on the User object from a Rule, it will return: ["internal-group-1", "internal-group-2"]
.
Metadata data types
Metadata fields support all JSON-compatible data types:
String
Number
Array
Object
Make sure to keep data types consistent between users. For example, if you store a value as a string for one user (user.user_metadata.age = "23"
) and as a number for another user (user.user_metadata.age = 23
), you may encounter issues when retrieving the data.
Limitations and restrictions
Rate limits
When you update metadata during login with Rules or Actions, you are subject to your tenant’s rate limits. To learn more, read Management API Endpoint Rate Limits.
Size limits and storage
There is a 1 MB per-user limit on user data that can be indexed, queried, and returned by the user search endpoint. If a user profile is larger than 1 MB, any attribute values larger than 256 characters within
app_metadata
anduser_metadata
will not be searchable or returned in a search result. If the user profile is still over 1 MB after omitting these large values, then none of theapp_metadata
anduser_metadata
attributes will be searchable or returnable for that user. Auth0 captures and logs instances where a user profile is still over 1MB after omittances under thewum
event code. The get user endpoint must be used to retrieve all metadata attributes for oversized user profiles.When you set the
user_metadata
field using the Auth0 Authentication API Signup endpoint, you can include a maximum of 10 string fields whose values do not exceed 500 characters each. For an example of working with metadata during a custom signup process, read Custom Signup.The
client_metadata
field can have a maximum of 10 keys. Its keys and values have a maximum length of 255 characters each and cannot contain UTF-8 special characters.
Restrictions
The app_metadata
field must 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