Appearance

Setting custom metadata for a single user ​

Privy allows you to set custom metadata on the user object to store any app-specific metadata. This field is a generic JSON object up to 1KB in size. The JSON can contain arbitrary key-value pairs where the key is a string and value is a string, integer, or boolean (ie {username: 'name', isVerified: true, age: 23}).

WARNING

Privy rate limits REST API endpoints that you may call from your server. If you suspect your team will require an increased rate limit, please reach out to support!

Using @privy-io/server-auth ​

Use the PrivyClient's setCustomMetadata method to set the custom metadata field for a user by their DID. As parameters, pass the user's DID as a string and the JSON object that you wish to set as custom metadata:

typescript
const user = await privy.setCustomMetadata('did:privy:XXXXXX', {username: 'name'});

If a matching user is found for the DID and the custom metadata object is valid, the method will return the corresponding User object with updated custom metadata. If no matching user is found, or the custom metadata input is malformed or too large (>1KB), the method will throw an error.

TIP

When using the setCustomMetadata function in TypeScript, you can specify a type generic in order to enable type inference on the method like so:

tsx
// TypeScript will throw a type error if customMetadata is not of type {key1: string}
const user = await privy.setCustomMetadata<{key1: string}>('did:privy:XXXXXX', customMetadata);

Using the REST API ​

To set the custom data for a user with a given DID, make a POST request to:

bash
https://auth.privy.io/api/v1/users/<did>/custom_metadata

Replace <did> with your desired Privy DID. It should have the format did:privy:XXXXXX.

Below is a sample cURL command for this request:

bash
curl --request POST https://auth.privy.io/api/v1/users/<user-did>/custom_metadata \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"
-d '{
  "custom_metadata": {username: "name", isVerified: true, age: 23}
}'

A successful response will include the user object associated with the DID, with updated custom_metadata, like below:

json
{
  "id": "did:privy:cfbsvtqo2c22202mo08847jdux2z",
  "created_at": 1667165891,
  "custom_metadata": {"username": "name"},
  "linked_accounts": [
    {
      "type": "email",
      "address": "[email protected]",
      "verified_at": 1667350653
    }
  ]
}

If there is no user associated with the provided DID, or the custom metadata input is malformed or too large (>1KB), the API will return an error.