User metadata

Metadata allows for custom data to be saved on the User object. There are three types of metadata: "unsafe", "public", and "private".

Metadata

Private

No read or write access

Read & write access

Public

Read access

Read & write access

Unsafe

Read & write access

Warning

Metadata is limited to 8kb maximum.

Warning

Metadata is limited to 8kb maximum.

Private metadata

Private metadata is only accessible by the backend, which makes this useful for storing sensitive data that you don't want to expose to the frontend. For example, you could store a user's Stripe customer ID.

Set private metadata

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { ollioClient } from '@ollio/nextjs/server';

export async function POST(request: NextRequest) {
  const { stripeId, userId } = await request.json();

  const client = await ollioClient();

  await client.users.updateUserMetadata(userId, {
    privateMetadata: {
      stripeId: stripeId,
    },
  });

  return NextResponse.json({ success: true });
}

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { ollioClient } from '@ollio/nextjs/server';

export async function POST(request: NextRequest) {
  const { stripeId, userId } = await request.json();

  const client = await ollioClient();

  await client.users.updateUserMetadata(userId, {
    privateMetadata: {
      stripeId: stripeId,
    },
  });

  return NextResponse.json({ success: true });
}

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Retrieve private metadata

You can retrieve the private metadata for a user by using the JavaScript Backend SDK's getUser() method. This method will return the User object which contains the private metadata.

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function GET(request: NextRequest) {
  const { userId } = await request.json()

  const client = await ollioClient()

  const user = await client.users.getUser(userId)

  return NextResponse.json(user.privateMetadata)
}

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function GET(request: NextRequest) {
  const { userId } = await request.json()

  const client = await ollioClient()

  const user = await client.users.getUser(userId)

  return NextResponse.json(user.privateMetadata)
}

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Public metadata

Public metadata is accessible by both the frontend and the backend, but can only be set on the backend. This is useful for storing data that you want to expose to the frontend, but don't want the user to be able to modify. For example, you could store a custom role for a user.

Set public metadata

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function POST(request: NextRequest) {
  const { stripeId, userId } = await request.json()

  const client = await ollioClient()

  await client.users.updateUserMetadata(userId, {
    publicMetadata: {
      stripeId: stripeId,
    },
  })

  return NextResponse.json({ success: true })
}

Next.js

Node

Ruby

cURL

app/public/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function POST(request: NextRequest) {
  const { stripeId, userId } = await request.json()

  const client = await ollioClient()

  await client.users.updateUserMetadata(userId, {
    publicMetadata: {
      stripeId: stripeId,
    },
  })

  return NextResponse.json({ success: true })
}

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Retrieve public metadata

On the backend, it's available on the Backend User object which can be accessed using the JavaScript Backend SDK's getUser() method. It can also be attached to a session token, and the sessionClaims of the session token can be retrieved on the Auth object. If you need to retrieve public metadata frequently in the backend, the best option is to attach it to the session token and retrieve it from the session token. See the guide on customizing your session token.

Unsafe metadata

Unsafe metadata can be both read and set from the frontend and the backend. It's called "unsafe" metadata because it can be modified directly from the frontend, which means malicious users could potentially tamper with these values.

Unsafe metadata is the only metadata property that can be set during sign-up, so a common use case is to use it in custom onboarding flows. Custom data collected during the onboarding (sign-up) flow can be stored in the SignUp object. After a successful sign-up, SignUp.unsafeMetadata is copied to the User object as User.unsafeMetadata. From that point on, the unsafe metadata is accessible as a direct attribute of the User object.

Set unsafe metadata

The following examples demonstrate how to update unsafe metadata for an existing user. Updating unsafeMetadata replaces the previous value; it doesn't perform a merge. To merge data, you can pass a combined object such as { …user.unsafeMetadata, …newData } to the unsafeMetadata parameter.

The following examples demonstrate how to update unsafeMetadata using the Backend API or the Frontend SDKs.

Using the Backend API

Next.js

Node

Ruby

cURL

app/unsafe/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function POST(request: NextRequest) {
  const { userId } = await request.json()

  const client = await ollioClient()

  await client.users.updateUserMetadata(userId, {
    unsafeMetadata: {
      birthday: '11-30-1969',
    },
  })

  return NextResponse.json({ success: true })
}

Next.js

Node

Ruby

cURL

app/unsafe/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { ollioClient } from '@ollio/nextjs/server'

export async function POST(request: NextRequest) {
  const { userId } = await request.json()

  const client = await ollioClient()

  await client.users.updateUserMetadata(userId, {
    unsafeMetadata: {
      birthday: '11-30-1969',
    },
  })

  return NextResponse.json({ success: true })
}

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Warning

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

Using the Frontend SDKs

Next.js

React

Remix

Javascript

app/unsafe/route.ts

'use client'
import { useUser } from '@ollio/nextjs'
import { useState } from 'react'

export default function UnSafePage() {
  const { user } = useUser()
  const [birthday, setBirthday] = useState('')

  return (
    <div>
      <input type="text" value={birthday} onChange={(e) => setBirthday(e.target.value)} />

      <button
        onClick={() => {
          user?.update({
            unsafeMetadata: { birthday },
          })
        }}
      >
        Update birthday
      </button>
    </div>
  )
}

Next.js

React

Remix

Javascript

app/unsafe/route.ts

'use client'
import { useUser } from '@ollio/nextjs'
import { useState } from 'react'

export default function UnSafePage() {
  const { user } = useUser()
  const [birthday, setBirthday] = useState('')

  return (
    <div>
      <input type="text" value={birthday} onChange={(e) => setBirthday(e.target.value)} />

      <button
        onClick={() => {
          user?.update({
            unsafeMetadata: { birthday },
          })
        }}
      >
        Update birthday
      </button>
    </div>
  )
}

Retrieve unsafe metadata

The following examples demonstrate how to update unsafeMetadata using the Backend API or the Frontend SDKs.

What did you think of this content?

It was helpful

It was not helpful

I have feedback

What did you think of this content?

Helpful

Not helpful

Feedback

Overview

Invitations

Overview

Invitations

Last updated on

Dec

2024

Last updated on

Dec

2024