Metadata Field Name Rules

The following sections cover rules and guidelines for setting the names of your metadata fields.

Avoid periods and ellipses

Metadata field names must not contain a dot. For example, use of the following field name would return a Bad Request (400) error:

{
    "preference.color": "pink"
}

One way of handling this limitation is to nest attributes:

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

Alternately, you can use any delimiter that is not . or $.

However, the usage of the . delimiter is acceptable in the data values such as in the below example:

{
    "preference": "light.blue"
}

Avoid dynamic field names

Do not use dynamic field names. For example, instead of using the following structure:

"participants": {
    "Alice" : {
        "role": "sender"
    },
    "Bob" : {
        "role": "receiver"
    }
}

Use this:

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

Field restrictions

The following fields may not be stored in the app_metadata field:

  • blocked
  • clientID
  • created_at
  • email
  • email_verified
  • global_client_id
  • globalClientID
  • identities
  • lastIP
  • lastLogin
  • metadata
  • user_id
  • loginsCount

Metadata size limits

Currently, Auth0 limits the total size of your user metadata to 16 MB. However, when using Rules and/or the Management Dashboard, your metadata limits may be lower.

When setting the user_metadata field with the Authentication API Signup endpoint, your metadata is limited to a maximum of 10 fields and 500 characters. Currently, Auth0 limits the total size of your user metadata to 16 MB. However, when using Rules and/or the Management Dashboard, your metadata limits may be lower.

When setting the user_metadata field using the Authentication API's Signup endpoint, you are limited to a maximum of 10 String fields and 500 characters.

Metadata and custom databases

If you are using a custom database, the app_metadata field should be referred to as metadata in the scripts you run to manage your metadata.

For example, you would not use this:

{
    "emails": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Instead, you would use this:

{
    "emails": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "metadata": {
        "plan": "full"
    }
}

Keep reading