User metadata

Store custom JSON data on user profiles with private, public, or unsafe visibility. Learn how to manage it via APIs and include it in session JWTs.

Hanko User Metadata Management Guide:

About Hanko:

Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

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

Prerequisites:

• Active Hanko project
• Understanding of API authentication
• Admin API access (for private and public metadata management)
• Basic knowledge of JSON data structures

Tasks You’ll Complete:

• 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

Hanko supports arbitrary user metadata storage. Metadata is organized into three distinct types, each with different access and modification permissions:

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

Each metadata type supports a maximum of 3,000 characters. Metadata is stored as compact JSON (whitespace is ignored). JSON syntax characters ({, :, ", }) 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 user object in the payload on the success state in a Login and Registration flow as well as in the payload on the profile_init state in a Profile flow.
  • Public metadata is returned as part of the response of the Get a user by ID endpoint.
• 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 User context object available on session JWT customization. See Session token customization for more details.

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 user object in the payload on the success state in a Login and Registration flow as well as in the payload on the profile_init state in a Profile flow.
  • Unsafe metadata is returned as part of the response of the Get a user by ID endpoint.
• 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 User context object available on session JWT customization. See Session token customization for more details.

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_metadata action in the Profile flow.

• Admin API:

  • Unsafe metadata can be set using the Patch metadata of a user endpoint.