Metadata Field Names and Data Types

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

Auth0 metadata is not a secure data store and should not be used to store sensitive information, such as high-risk secrets and Personally Identifiable Information (PII) like social security numbers or credit card numbers. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes.

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

But you can expand it like this:

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

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

Do this:

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

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

You should only store data related to user authentication in metadata. The storage and search capabilities of Auth0 are designed for use cases that do not require heavy search and/or update frequency.If you need to maintain detailed profile-related data for users, you should do so in an external system. You can store the user’s identifier from that system as a metadata field in Auth0.

Size limits and storage

Auth0 user profiles have a size limit of 10 KB. Writes that cause profiles to exceed this size limit succeed for now, but may start to fail. A tenant log flags profiles as oversized, and we strongly recommend bringing user profiles within the size limit to avoid errors.
For oversized user profiles that precede the size limit, there is a 1 MB per-user limit on user data that can be indexed, queried, and returned when using the Management API’s List or Search Users endpoint. To retrieve all user attributes for a large user profile, get users by ID or email.
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

Manage Users

Manage Access

Metadata Field Names and Data Types

Metadata field names

Accepted characters

Dynamic field names

Name collision

Metadata data types

Limitations and restrictions

Rate limits

Size limits and storage

Restrictions

Learn more

​Metadata field names

​Accepted characters

​Dynamic field names

​Name collision

​Metadata data types

​Limitations and restrictions

​Rate limits

​Size limits and storage

​Restrictions

​Learn more

Metadata field names

Accepted characters

Dynamic field names

Name collision

Metadata data types

Limitations and restrictions

Rate limits

Size limits and storage

Restrictions

Learn more