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 Event-Based Updates

The Audit Webhook feature allows you to receive events when users are created, modified, or deleted. Note that these events are not delivered in real-time and include an internal throttling mechanism to manage system load. This is useful when:

You need to track user changes without 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 the Connectors page and Select the "Audit Webhook".
Configure the following:
- Name: The Audit Webhook instance name.
- Base URL: Your API endpoint to receive audit events.
- Authentication Type: (Optional) Based on your implementation, choose one from the following - None, Bearer Token, API Key, Basic or OAuth2.0.
- Event Type: Select "Stream filtered audit events only", Select "Action" as the key, "Includes" as the operator, then add User Created, User Modified, and User Deleted.
Test and save the Audit Webhook instance.

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 about available events, please review the Audit Events article.

Example Use Case: Keeping an External Database in Sync

If your system needs to track user record modifications, an audit webhook can push changes to your API, which updates your database. Note that due to the throttling mechanism, there may be a delay between when a change occurs and when your system receives the event.

Choosing the Right Approach

Use Case	Recommended Method
Periodic batch updates of users	Search Users API
Event-based tracking of user changes	Audit Webhook
Hybrid approach (initial sync + event-based 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 user changes and keep your data updated.
Periodically re-sync using the API as a fallback in case of webhook failures or to catch any missed events due to throttling.

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