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

  Was this helpful?

  Yes /No
  This, however, is accepted:

  {
    "color" : "light.blue"
  }
  

  Was this helpful?

  Yes /No
  As a workaround, you can convert the first example to something like this:

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

  Was this helpful?

  Yes /No
  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"
          }
      }
  
  

  Was this helpful?

  Yes /No
  Use this:

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

  Was this helpful?

  Yes /No

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.

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.

To learn more, read Management API Endpoint Rate Limits.

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

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

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