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.
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 and context.clientMetadata in Rules. 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

Avoid using the same name for app_metadata fields and root profile fields. Within the rules scope, app_metadata is squashed into the root profile and may override root properties.

For example, if a SAML identity provider returns a groups field and the user has an app_metadata.groups field, then user.groups will be equal to app_metadata.groups and not user.groups.

  • Metadata must be a valid JSON object.

  • Metadata cannot contain . (dot) or a $ (dollar sign) in key field names in user_metadata, app_metadata, or clientMetadata. If you use these characters, you will get an Internal Server (500) error. This is not allowed:

    {
      "preference.color" : "pink"
    }
    
    This, however, is accepted:
    {
      "color" : "light.blue"
    }
    
    As a workaround, you can convert the first example to something like this:
    {
      "preference" : {"color" : "pink" }
    }
    
    Or you could use a different delimiter character besides . (dot) or $ (dollar sign).

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

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

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.

Limitations and restrictions

Rate limits

Setting user and app metadata is subject to your tenant’s rate limits and may affect login throughput. Even though a single call is made to update the user profile, that operation is still subject to your tenant’s “Write User” rate limits.

We recommend that you don't store profile-related information in metadata. This data is intended to be used for authentication and authorization purposes. The metadata and search capabilities of Auth0 are not designed for marketing research or anything else that requires heavy search or update frequency. Your system is likely to run into scalability and performance issues if you use Auth0 for this purpose. A better approach is to store data in an external system and store a pointer (the user ID) in Auth0 so that backend systems can fetch the data if needed. Data not related to user authentication should always be stored in an external database.

To learn more, read Management API Endpoint Rate Limits.

Size limits and storage

  • Both app_metadata and user_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 10 String fields and 500 characters. For an example of working with metadata during a custom signup process, see Custom Signup.

  • 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 clientMetadata (application metadata) object keys and value strings have a maximum length of 255 characters. Application metadata can have a maximum of 10 keys.

Restrictions

The app_metadata 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

Learn more