Users
User Metadata
Hanko User Metadata Management Guide
About Hanko: Hanko is a modern passwordless authentication solution that simplifies user sign-in experiences by eliminating passwords in favor of secure alternatives like passkeys, email magic links, and biometric authentication.What This Guide Covers: This guide explains how to work with Hanko’s user metadata system, including the three metadata types (private, public, unsafe), their access permissions, character limitations, and how to read and modify metadata through various APIs.Key Technologies:- Hanko Public API
- Hanko Admin API
- JWT Templates and Session Customization
- User Profile Management
- JSON Data Storage
- Active Hanko project
- Understanding of API authentication
- Admin API access (for private and public metadata management)
- Basic knowledge of JSON data structures
- Understand the three metadata types and their access levels
- Learn character limits and JSON storage requirements
- Access metadata through Public and Admin APIs
- Modify metadata using appropriate endpoints
- Implement metadata in JWT templates for session customization
- Choose the right metadata type for your use case
| Metadata type | Public API | Admin API |
|---|---|---|
| Private | No read or write access | Read and write access |
| Public | Read access | Read and write access |
| Unsafe | Read access and write access | Read and write access |
{, :, ", }) count toward the character limit.
Multibyte UTF-8 characters (like emojis or non-Latin characters) count as 1 character each.
Private metadata
Use private metadata for sensitive information that must remain hidden from client applications (e.g., internal flags/IDs, configuration settings, or access control details).Accessing private metadata
Private metadata is accessible exclusively through the Admin API using the Get metadata of a user endpoint.Setting private metadata
Private metadata can only be created and modified through the Admin API using the Patch metadata of a user endpoint.Public metadata
Use public metadata for non-sensitive information that should be readable but not modifiable by client applications (e.g., user roles, UI preferences, display settings).Accessing public metadata
Public metadata is accessible through the Public API, Admin API, and JWT templates for session customization:Public API:- Public metadata is returned in the
userobject in the payload on thesuccessstate in a Login and Registration flow as well as in the payload on theprofile_initstate in a Profile flow. - Public metadata is returned as part of the response of the Get a user by ID endpoint.
- Public metadata is returned in the
Admin API:- Public metadata is returned as part of the response of the Get metadata of a user endpoint.
- Public metadata is returned as part of the response of the Get a user by ID endpoint.
JWT Templates:- Public metadata can be accessed through the
Usercontext object available on session JWT customization. See Session token customization for more details.
- Public metadata can be accessed through the
Setting public metadata
Public metadata can only be created and modified through the Admin API using the Patch metadata of a user endpoint.Unsafe metadata
Use unsafe metadata for non-sensitive, temporary, or experimental data that doesn’t require strict safety guarantees.Accessing unsafe metadata
Unsafe metadata is accessible through the Public API, Admin API, and JWT templates for session customization:Public API:- Unsafe metadata is returned in the
userobject in the payload on thesuccessstate in aLoginandRegistrationflow as well as in the payload on theprofile_initstate in aProfileflow. - Unsafe metadata is returned as part of the response of the Get a user by ID endpoint.
- Unsafe metadata is returned in the
Admin API:- Unsafe metadata is returned as part of the response of the Get metadata of a user endpoint.
- Unsafe metadata is returned as part of the response of the Get a user by ID endpoint.
JWT Templates:- Unsafe metadata can be accessed through the
Usercontext object available on session JWT customization. See Session token customization for more details.
- Unsafe metadata can be accessed through the
Setting unsafe metadata
Unsafe metadata can be created and modified through both the Public API and Admin API:-
Public API:- Unsafe metadata can be set using the
patch_metadataaction in the Profile flow.
- Unsafe metadata can be set using the
-
Admin API:- Unsafe metadata can be set using the Patch metadata of a user endpoint.