Tracking User Updates

Overview

Tracking user updates is essential for various use cases such as data analytics, user activity monitoring, and access control adjustments. Descope provides two primary methods to track user updates effectively:

Search Users API - Retrieve users based on their creation or modification timestamps.
Audit Webhooks - Stream real-time audit events for user actions such as creation, modification, and deletion.

This guide will explore both approaches, their use cases, and how to implement them in your system.

Method 1: Using the Search Users API

The Search Users API allows you to filter users based on various attributes, including their creation or last modification timestamps. This is useful when you need to:

Track newly created users over a specific period.
Monitor modifications to existing users.
Maintain an up-to-date user cache for analytics or reporting.

API Endpoint

Endpoint: POST /v2/mgmt/user/search. The docs are here.

Search Users API Request Body

Below is an example of the request body:

{
  "loginId": "",
  "tenantIds": [],
  "roleNames": [],
  "limit": "",
  "text": "",
  "page": "",
  "ssoOnly": "",
  "withTestUser": "",
  "testUsersOnly": "",
  "customAttributes": {},
  "statuses": [],
  "emails": [],
  "phones": [],
  "ssoAppIds": [],
  "sort": [],
  "loginIds": [],
  "fromCreatedTime": "",
  "toCreatedTime": "",
  "fromModifiedTime": "",
  "toModifiedTime": ""
}

Search Users API Parameters

The API provides the following parameters to filter users:

Parameter	Type	Description
`fromCreatedTime`	int	Include users created on or after this time (Unix epoch seconds).
`toCreatedTime`	int	Include users created on or before this time (Unix epoch seconds).
`fromModifiedTime`	int	Include users modified on or after this time (Unix epoch seconds).
`toModifiedTime`	int	Include users modified on or before this time (Unix epoch seconds).

Example Use Case: User Data Synchronization

If you store user data in a database and need to periodically update it, you can use the fromModifiedTime parameter to fetch all users modified since the last synchronization timestamp.

Example API Call

POST /v2/mgmt/user/search
{
  "fromModifiedTime": 1700000000
}

This request will return all users who were updated on or after Unix epoch time 1700000000.

For more details, visit the Search Users API documentation.

Method 2: Using Audit Webhooks for Real-Time Updates

The Audit Webhook feature allows you to receive real-time events when users are created, modified, or deleted. This is useful when:

You need immediate updates instead of polling the Search Users API.
Your system relies on event-driven architectures.
You want to log or trigger actions based on user modifications.

Setting Up an Audit Webhook

Navigate to Project Settings > Webhooks in the Descope Console.
Click + Add Webhook and configure the following:
- URL: Your API endpoint to receive audit events.
- Event Type: Select UserCreated, UserModified, and UserDeleted.
- Authentication: (Optional) Secure with API keys or authentication tokens.
Save and activate the webhook.

Example Audit Event Payload

When a user is modified, an event like the following is sent to your audit webhook endpoint:

{
  "Change": {
    "added_multi_tenant_roles": [
      "xx"
    ],
    "added_roles": [
      "xx"
    ],
    "custom_attribute_emailConsent": true,
    "custom_attribute_myAttribute": true,
    "display_name": "Test Me",
    "family_name": "Test",
    "given_name": "Me",
    "middle_name": "Middle",
    "phone": "12223334455"
  },
  "correlation_id": "xx",
  "request_details": {
    "contentLength": "956",
    "headers": {
      "descope": {
        "cf-bot-score": "99",
        "cf-connecting-ip": "xx",
        "cf-ja3-hash": "xx",
        "cf-ray": "xx-DFW",
        "cf-verified-bot": "false",
        "x-request-id": "xx"
      },
      "http": {
        "origin": "https://app.descope.com",
        "referer": "https://app.descope.com/",
        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
      }
    },
    "host": "console.descope.com",
    "method": "POST",
    "uri": "/console/v1/users/xx",
    "url": "/console/v1/users/xx"
  }
}

For more information on Audit Events, visit our docs.

Example Use Case: Keeping an External Database in Sync

If your system needs to immediately update user records upon modification, an audit webhook can push changes to your API, which updates your database in real-time.

Choosing the Right Approach

Use Case	Recommended Method
Periodic batch updates of users	Search Users API
Real-time synchronization	Audit Webhook
Hybrid approach (initial sync + real-time updates)	Both

Hybrid Approach: Combining API & Webhooks

For an optimal setup:

Use the Search Users API to initially populate your user database.
Set up an Audit Webhook to capture real-time changes and keep your data updated.
Periodically re-sync using the API as a fallback in case of webhook failures.

Conclusion

Tracking user updates is crucial for maintaining accurate records and responding to changes efficiently. By leveraging Descope's Search Users API and Audit Webhooks, you can implement a reliable and scalable approach to user monitoring, whether for data analytics, security audits, or operational needs.

Was this helpful?

On this page