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
Metadata must be a valid JSON object.
Metadata cannot contain
.
(dot) or a$
(dollar sign) in key field names inuser_metadata
,app_metadata
, orclientMetadata
. If you use these characters, you will get an Internal Server (500) error. This is not allowed:This, however, is accepted:{ "preference.color" : "pink" }
Was this helpful?
/As a workaround, you can convert the first example to something like this:{ "color" : "light.blue" }
Was this helpful?
/Or you could use a different delimiter character besides{ "preference" : {"color" : "pink" } }
Was this helpful?
/.
(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:
Use this:"participants": { "Alice" : { "role": "sender" }, "Bob" : { "role": "receiver" } }
Was this helpful?
/"participants": [ { "name": "Alice", "role": "sender" }, { "name" : "Bob", "role": "receiver" } ]
Was this helpful?
/
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.
To learn more, read Management API Endpoint Rate Limits.
Size limits and storage
Both
app_metadata
anduser_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 10String
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