Custom Metadata, External ID, and JWT Templates

When a user logs in to your application, every millisecond counts. To create an excellent experience, you must determine this user’s:

• permissions (what they’re allowed to do)
• preferences (like language, theme, region, etc)
• settings or policies for organizations they belong to

Speed is Critical

If this bootstrapping process is slow, your users get frustrated and leave. Many developers try using a single "bootstrap" API call that loads everything at once - blocking frontend rendering.

Over time, this approach becomes bloated, slowing down the entire experience and creating a dangerous single point of failure. Any issue with this endpoint breaks your entire application for everyone.

How can you balance snappy retrieval of custom user data without adding additional network round trips? By using WorkOS Custom Metadata.

AuthKit Expands Metadata and JWT Control

WorkOS AuthKit provides three new capabilities:

1. Custom metadata - Provides the ability to store important user and organization data on the objects themselves.
2. JWT templates - Customize session JSON web tokens with custom metadata and claims
3. External IDs - Simplifies migrations by allowing your app to maintain the same object ids.

Developers can use these capabilities to deliver essential metadata directly in the authentication response, allowing users to access your application without delay or disruptive re-rendering.

These new capabilities work together to store the necessary context in WorkOS and then define how it should be presented in the JWT your application uses.

Let’s examine each component in more detail.

Custom metadata

Custom metadata allows for storing custom string values (metadata) on both users and organization objects. These can be used for a variety of needs, such as saving user preferences or application configuration.

WorkOS is designed to support complex b2b apps, so custom metadata is also available on organization objects. Many important pieces of context may only exist at the organization level, including subscriptions, product trial expirations, license keys, and organization settings.

Custom metadata is set from an application’s backend (via API). Custom metadata is also private, meaning only backend services with a WorkOS API token can access the values. This simplicity avoids keeping track of which attributes may be public or "untrusted" for security. All WorkOS metadata is secure.

There are many cases you may want to expose metadata to the frontend application. This is done through JWT templates.

How to use JWT templates

Data available in JWT sessions is immediately available to your application without requiring any backend API request, resulting in large speed improvements. Furthermore, JWT customization allows for increased compatability with 3rd-party systems that might require custom claims or scopes.

JWT templates allow you to set nearly any arbitrary field and format for your app.

The WorkOS Dashboard provides a rich text editor experience for managing JWT template. In addition to basic editing, it supports auto-complete functionality for existing custom metadata fields and standard WorkOS fields including roles, permissions, and attributes. Templates can also be validated and previewed before before being applied.

{
   "aud": "SuperApp",
   "urn:my_app:full_name": "{{user.firstName}} {{user.firstName}}" 
   "urn:my_app:department": {{user.sso_attributes.department}},
   "urn:my_app:organization_tier": {{organization.metadata.tier}}, 
   "urn:my_app:user_city": {{user.metadata.address}},
   "urn:third_party_app:address": {{user.metadata.address}},
}

WorkOS supports a moustache-like syntax for customizing the template. This allows you to combine strings or even provide defaults if a value such as null.

Templates can be validated in a staging environment to ensure they are correct before deploying them in production. This allows you to make changes with confidence and avoid issues from template changes with mistakes.

External ID

While some WorkOS users build their app entirely with AuthKit, most scaled users already have a preexisting authentication solution. Whether this is a cloud service, an open-source library, or a homegrown codebase, these existing systems have their own IDs for users and organizations. Migrations can sometimes be tricky since these IDs are deeply embedded across the application stack and with 3rd-party systems, such as CRMs or internal tools.

WorkOS now makes migrating existing users and authentication even easier by introducing an External ID. This value can be set by the developer on users and organizations and uniqueness is enforced.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const organization = await workos.organizations.createOrganization({
  name: 'Foo Corp',
  externalId: '2fe01467-f7ea-4dd2-8b79-c2b4f56d0191',
});

Users and orgs can also be quickly retrieved using the external ID value.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const user = await workos.userManagement.getUserByExternalId(
  'f1ffa2b2-c20b-4d39-be5c-212726e11222',
);

After migrating to WorkOS, your application can switch to native WorkOS IDs or continue using external IDs. Either way, WorkOS has you covered.

More customization for better DX

While WorkOS always aims to provide the best out-of-the-box experience for enterprise applications, every app is different, and so the ability to customize certain behaviors is critical. With these three new capabilities—custom metadata, JWT templates, and external ID—WorkOS provides even more flexibility for any integration.

Learn more about how metadata and JWT templates work in the docs, and get started for free in the dashboard.