Custom Metadata: How It Works

Last week, we released a long awaited and asked for feature in PropelAuth, Custom Metadata on both users and organizations! However, the term “metadata” is nebulous and vague, so today we’re excited to walk through this new aspect of the product, and how you can start customizing to your heart’s content.

What was there before?

Currently, there are a few default values that are associated with User and Organization objects in PropelAuth. We call these values, properties. In Organizations, these are things like the organization id, the name of the organization, or the boolean can_setup_saml. On User objects, these are the user id and the email address of the user.

Before the newest release, you did have the ability to manipulate the schema of these user objects a bit. Through the dashboard, you were able to toggle a few properties, like the user’s first and last name, or their username.

What is there now?

You can now add customizable information to the User and Organization objects as JSON objects. What can you use this for? Well… anything you want, it’s arbitrary json. You can store A/B testing groups, routing logic, display names, who they are rooting for in the chess world championship, it’s up to you!

These exist now on the objects under new “metadata” fields that you can access through a few new endpoints we have added to the product.

How do I do this?

Through our new functions! In our libraries, you will find new functions that can update the metadata field on User and Organization objects. For example, let’s say you have a Node backend, and somewhere in there you’d like to add a custom field to some users, let’s say a testing group. Then you would use the updateUserMetadata function, like this:

await auth.updateUserMetadata("3954c1a9-8575-4a24-9d3a-aa66f4be7511", {
    metadata: {
        "user_testing_group": "A",
    }
})

// later on...
const user = await auth.fetchUserMetadataByUserId("3954c1a9-8575-4a24-9d3a-aa66f4be7511")
console.log(user)

//returns
{
  email: 'brooks@test.com',
  metadata: { user_testing_group: 'A' },
  locked: false,
  enabled: true,
  ....
  mfaEnabled: false,
  createdAt: 1680895145,
  lastActiveAt: 1682024563
}

And later on, if you were to try and pull this user, the output would look like:

{
  email: 'brooks@test.com',
  metadata: { user_testing_group: 'A' },
  locked: false,
  enabled: true,
  ....
  mfaEnabled: false,
  createdAt: 1680895145,
  lastActiveAt: 1682024563
}

Some Examples

There are a few different use cases for customizable metadata that we have seen from customers in the past. For instance, for typical specialized user information, you could store specific metadata like

{
  user_id: "3954c1a9-8575-4a24-9d3a-aa66f4be7511",
  metadata:  {
    "age": 37,
	"preferred_communication_method": "email"
  },
}

For tracking changes in state to the user for marketing purposes, you could use something like

{
  user_id: "3954c1a9-8575-4a24-9d3a-aa66f4be7511",
  metadata:  {
    "has_seen_feature_announcement_x": true,
	"has_seen_feature_announcement_y": true,
	"has_seen_feature_announcement_z": false
  },
}

By default, there isn’t an ability to make an organization “internal” versus “external,” but there is with metadata!

{
  org_id: "0b4079cd-8826-49d4-a8e5-35f003e0d843",
  metadata:  {
    "is_internal_org_with_special_permissions": true
  },
}

We’re very excited to see this released to you all, and as always, if you have any questions, please reach out at support@propelauth.com