Organization metadata

Organization metadata lets you store custom information about an Organization that is not part of the standard fields, such as custom attributes that are specific to your application. This is useful for advanced user segmentation, analytics, or storing application-specific data like subscription tier, department, or region.

Metadata is stored on the Organization and OrganizationMembership objects.

Types of metadata

There are two types of Organization metadata: public and private.

Both the Organization and OrganizationMembership objects have the metadata fields: publicMetadata and privateMetadata.

• Use the publicMetadata property if you need to set some metadata from your backend and have them displayed as read-only on the frontend.
• Use the privateMetadata property if the custom attributes contain sensitive information that should not be displayed on the frontend.

Set Organization metadata

You can set Organization metadata in the Clerk Dashboard⁠ or using Clerk's Backend API. See the updateOrganizationMetadata() and updateOrganizationMembershipMetadata() methods for more information.

Access public metadata

To access public metadata on the frontend, it's available on the Organization object, which can be accessed using the useOrganization() hook.

To access public metadata on the backend, it's available on the Backend Organization object which can be accessed using the getOrganization() method. This method will return the Organization object which contains the public metadata. However, this method is subject to rate limits, so if you are accessing the metadata frequently, it's recommended to attach it to the user's session token.

Metadata in the session token

Retrieving metadata from the Organization or OrganizationMembership objects on the server-side requires making an API request to Clerk's Backend API, which is slower and is subject to rate limits. You can store it in the user's session token, which doesn't require making an API request as it's available on the user's authentication context. However, there is a size limitation to keep in mind. Clerk stores the session token in a cookie, and most browsers cap cookie size at 4KB⁠. After accounting for the size of Clerk's default claims, the cookie can support up to 1.2KB of custom claims. Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly.

If you need to store more than 1.2KB of metadata, you should store the extra data in your own database instead. If this isn't an option, you can move particularly large claims out of the token and fetch them using a separate API call from your backend, but this approach brings back the issue of making an API request to Clerk's Backend API, which is slower and is subject to rate limits.

Another limitation of storing metadata in the session token is that when you modify metadata server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either force a JWT refresh after metadata changes or handle the delay in your application logic.

If you've considered the limitations, and you still want to store metadata in the session token:

1. In the Clerk Dashboard, navigate to the Sessions⁠ page.
2. Under Customize session token, in the Claims editor, you can add any claim to your session token that you need and select Save. To avoid exceeding the session token's 1.2KB limit, it's not recommended to add the entire organization.public_metadata or organization_membership.public_metadata object. Instead, add individual fields as claims, like organization.public_metadata.birthday. When doing this, it's recommended to leave particularly large claims out of the token to avoid exceeding the session token's size limit. See the example for more information.

Next steps

Now that you understand Organization metadata, you can:

• Add metadata to invitations to track invitation sources or assign attributes
• Create and manage Organizations to see metadata in action
• Control access based on Roles and Permissions
• Use Organization slugs in URLs for tenant-specific routing