Virtneu Auth Docs

App and user metadata

Read and replace JSON metadata with revision checks.

Metadata is scoped to an app and environment. In the HTTP API and SDK, use metadata for app settings, profile_metadata for user profile and preferences, and managed_metadata for user attributes managed by your application. Both user objects are written through authorized backend calls or Studio.

ActionSDKHTTP
Read app metadatagetApplicationMetadata()GET /v1/application/metadata
Replace app metadatareplaceApplicationMetadata(input)PUT /v1/application/metadata
Read user metadatagetUserMetadata(userId)GET /v1/users/{userId}/metadata
Replace user metadatareplaceUserMetadata(userId, input)PUT /v1/users/{userId}/metadata

Read operations require metadata:read and replacement requires metadata:write. The user ID is the Virtneu Auth user ID.

Read the current value first. Pass the returned revision and the full updated object to the replacement method. User metadata replacement requires both objects. Each object can be up to 6144 UTF-8 bytes after compact JSON serialization. Top-level values must be JSON objects. Use an empty object to clear its value.

const { data } = await auth.getUserMetadata(userId);
await auth.replaceUserMetadata(userId, {
  revision: data.revision,
  profile_metadata: { ...data.profile_metadata, locale: 'en' },
  managed_metadata: data.managed_metadata,
});

If another update wins first, the API returns 409 METADATA_CONFLICT. Read the latest data, merge your change, and retry with the new revision.

Database storage

Studio’s Database schema page shows the physical tables and columns in the selected environment.

HTTP / SDK fieldDatabase columnPurpose
Application metadataapplication_metadata.metadataShared app settings for this environment
User profile_metadatauser_metadata.profile_metadataOne user's profile and preferences
User managed_metadatauser_metadata.managed_metadataUser attributes managed by your application

Each environment has its own database. Application metadata has at most one row with id = 1. User metadata has at most one row per user_id, linked to user.id. Rows are created on the first save. Before that save, reads return empty objects and revision 0; the user must already exist. The two user objects share a revision and are replaced together. Deleting a user also deletes their metadata.

Migration 0015_user_metadata_names.sql introduced the current user-column names while preserving their values and revisions. New environments apply the complete migration sequence during provisioning. The current API and SDK accept only profile_metadata and managed_metadata, introduced in SDK 0.2.0; the former user_metadata and app_metadata payload fields are rejected with 400 INVALID_METADATA. The physical table is still named user_metadata.

Example data and editing

An environment can store shared settings such as a support email:

{
  "revision": 1,
  "metadata": { "support_email": "support@example.test" }
}

A user can have profile preferences and an application-assigned beta group:

{
  "revision": 1,
  "profile_metadata": { "locale": "en", "theme": "dark" },
  "managed_metadata": { "beta_group": "early_access" }
}

In the database, locale and theme are inside profile_metadata, while beta_group is inside managed_metadata. These are custom keys chosen by your backend.

In Studio, open an App and choose an environment’s Application metadata panel to edit shared settings. Open a user’s details to edit Profile metadata and Managed metadata. The Database schema page shows column structure.

Both user objects use the same metadata:write service scope and the same Studio write permission. Your backend decides which changes an end user can request.

To update shared settings from your backend:

const { data: application } = await auth.getApplicationMetadata();
await auth.replaceApplicationMetadata({
  revision: application.revision,
  metadata: {
    ...application.metadata,
    support_email: 'support@example.test',
  },
});

User replacement sends both complete objects. Include existing keys that you want to keep in each object. Sending {} clears that object, and a stale revision returns 409 METADATA_CONFLICT.

After a timeout, read the latest value and compare it with the intended change before retrying. A successful request may have incremented the revision even if its response was lost. A missing user returns 404 RESOURCE_NOT_FOUND; invalid objects or revisions return 400 INVALID_METADATA.

On this page