Skip to content

User metadata

User metadata

The User Metadata feature allows the storage and retrieval of custom user-specific data within your application. This feature allows you to store metadata on the users.

Create or update metadata

Method: PUT Endpoint: /api/user/{userId}/metadata/{key} Description: Creates or updates a single metadata record. If a key already exists, the value will be overwritten.

Info

Ensure that metadata keys are unique. If not, only a single arbitrary value will be saved per key.

Example request

1
2
3
4
5
6
7
PUT /api/user/jane.doe@example.com/metadata/profile-theme
Content-Type: application/json

{
  "value": "Dark Mode",
  "profileClaim": true
}

Delete metadata

Method: DELETE Endpoint: /api/user/{userId}/metadata/{key} Description: Permanently deletes user metadata for the provided key.

Warning

Deleting metadata is irreversible. Ensure that the key provided is correct before proceeding.

Example request

1
DELETE /api/user/jane.doe@example.com/metadata/profile-theme

Retrieve metadata

Method: GET Endpoint: /api/user/{userId}/metadata Description: Retrieves all metadata for a given user.

Example response

1
2
3
4
5
6
7
8
9
{
  "metadata": [
    {
    "key": "theme",
    "value": "Dark mode",
    "profileClaim": true
    }
  ]
}

Bulk update metadata

Method: PUT Endpoint: /api/user/{userId}/metadata Description: Adds multiple metadata key-value pairs in bulk. Pre-existing entries for the user will be permanently removed.

Warning

Bulk updates overwrite existing metadata. Use with caution to avoid unintentional data loss.

Example request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
PUT /api/user/jane.doe@example.com/metadata
Content-Type: application/json

{
  "metadata": [
    {
      "key": "preferred-language",
      "value": "English",
      "profileClaim": false
    },
    {
      "key": "theme",
      "value": "Dark Mode",
      "profileClaim": true
    }
  ]
}

Profile claims in jwt

When a claim is marked as profileClaim: true, it is included in the JWT generated during user authentication. These claims are prefixed with metadata_ to distinguish them from other data in the JWT. This prefixing helps in identifying and managing user-specific metadata effectively.

Example

If you create a public claim with the key user-theme and value Light, it will appear in the JWT as: 

1
2
3
{  
  "metadata_user-theme": "Light"  
}

Security considerations

Warning

Notice that all profileClaims are included in the JWT and can be read by any party the JWT is shared with including the user.

By following these guidelines, you can effectively manage user metadata, providing both flexibility and security in your application's data management strategy.