Metadata Field Names and Data Types

Auth0 distinguishes between three types of metadata used to store specific kinds of information.

Field names must not contain the . (dot) or $ (dollar sign) characters.

For example, this is not allowed:

{
  "preference.color": "pink"
}

But you can expand it like this:

{
    "preference": { 
        "color": "pink" 
    }
}

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

Do this:

{
    "participants": [
        {
            "name": "Alice",
            "role": "sender"
        },
        {
            "name" : "Bob",
            "role": "receiver"
        }
    ]
}

Avoid using the same name for app_metadata fields and root profile fields. Within the Rules scope, app_metadata fields are merged onto the root profile and 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"
        ]
    }
}

When you read the groups field on the User object from a Rule, it will return: ["internal-group-1", "internal-group-2"].

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.

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.

• The app_metadata and user_metadata fields have a combined maximum limit of 16 MB total per user. There is no limit to the number of properties that may be stored in these fields.

• 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.

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

• Manage Metadata with Rules
• Manage Metadata Using the Management API
• Configure Application Metadata
• User Data Storage