What Is a UID?
In Piano, a UID (also displayed as User ID) is the core identifier assigned to every user record. It functions as the primary key that uniquely identifies a user within an application and links that user to all associated data across the platform.
Because the UID serves as the foundation of a user's identity in Piano, it is intended to be permanent and should be defined correctly at the time of user creation.
How a UID Is Assigned
The way a UID is assigned depends on your integration type.
Identity Management Integrations
When users are created through the Piano API, the Piano dashboard, or via registration on your website, the UID is generated by Piano at the time of creation and cannot be modified afterward.
UIDs generated by Piano are randomly-created 15 character alphanumeric strings consisting of uppercase and lowercase letters as well as numbers.
Identity Linking Integrations
When using Identity Linking, the UID is automatically derived from the JWT provided by your external system. Piano reads the user identifier from the sub claim in the JWT and assigns it as the UID.
Because your external system is the source of truth, the UID in Piano will always reflect the identifier supplied in the JWT.
What Is Linked to a UID
The UID ties together all of the following data for a given user:
-
Identity Management identity (profile, credentials, SSO links)
-
Subscriptions and entitlements
-
Payments and billing history
-
Historical analytics
UID Format Guidelines
To minimize integration and downstream processing issues, Piano recommends the following format for UIDs:
|
Guideline |
Recommendation |
|---|---|
|
Length |
Up to 255 characters |
|
Allowed characters |
Alphanumeric only (hyphens may also be acceptable depending on configuration) |
|
Avoid |
Spaces and reserved/special characters (e.g., |
If your organization has strict requirements (e.g., GUID-style identifiers), standardize your UID format across all connected systems before creating users in Piano.
Can a UID Be Changed?
A UID is not expected to change after a user has been created. The public API endpoint /publisher/user/update does not support UID modifications, and under normal circumstances there should be no need to update it.
For Identity Linking integrations, the UID is sourced directly from your external identity provider, so it is inherently synchronized.
If you encounter an exceptional situation where a UID change appears necessary (e.g., a data migration error or a duplicate record created by an integration issue), please contact Piano Support at support@piano.io.