Get User Metadata Keys

Overview

Discover the custom metadata keys (and sample values) currently stored on tenant users.

These keys help you build filter UIs for metadata.<key> query parameters on list endpoints such as List Users. Instead of hard-coding filter fields, call this endpoint to learn which keys exist, how often they appear, and which distinct values are in use.

When to use this endpoint?

Use Get User Metadata Keys when:

Building dynamic filter controls for metadata.<key>=value on List Users.
You need to know which metadata keys exist across the tenant’s users.
Populating dropdowns with distinct values (for example tier → gold / silver).
Auditing custom fields before updating user metadata via Update User.

GET{baseUrl}/api/{apiVersion}/client/users/metadata-keys

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
is-tenant	true	Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.

Success Response (HTTP 200 OK)

On success, the API returns each metadata key with usage counts and distinct values you can use for filter UIs.

json

1{2  "success": true,3  "message": "Metadata keys fetched successfully",4  "data": {5    "keys": [6      {7        "key": "workspaceId",8        "count": 57,9        "totalValues": 3,10        "values": [11          "c1",12          "c2",13          "c3"14        ]15      },16      {17        "key": "tier",18        "count": 12,19        "totalValues": 2,20        "values": [21          "gold",22          "silver"23        ]24      }25    ]26  },27  "error": null28}

Common Errors

HTTP 200 OK means metadata keys were fetched successfully. Failures usually indicate missing tenant headers or an invalid token.

Code	Reason
400 Bad Request	Required headers are missing or invalid.
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching metadata keys.

Best Practices

Load metadata keys when mounting your filter bar so options stay in sync with stored user data.
Map each returned key to a metadata.<key> query param on List Users.
Prefer the provided values array for select inputs when the set is small.
Re-fetch keys after bulk metadata updates so new fields appear in the UI.

Ready to filter by metadata

Use the returned keys to build filter controls, then call List Users with metadata.<yourKey>=value (for example metadata.tier=gold).

Overview

Discover the custom metadata keys (and sample values) currently stored on tenant users.

When to use this endpoint?

Use Get User Metadata Keys when:

Building dynamic filter controls for metadata.<key>=value on List Users.
You need to know which metadata keys exist across the tenant’s users.
Populating dropdowns with distinct values (for example tier → gold / silver).
Auditing custom fields before updating user metadata via Update User.

Header

Value

Description

is-tenant

true

Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create).

x-client-id

Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable.