Auditing

The Descope service logs events to an Audit trail within the Descope UI. The Audit trail can be found in the Console. The Descope audit trail is stored on a project level. Descope logs creation, edits, deletion, and login of users, including the authentication method, flowID, user, loginId, and tenantId. The timestamp, type of alert, and actions are logged. You can also display other columns apart from the default ones appearing in the audit table which also can be a part of smart search using the filter available. These include Device, Method, Country, Remote Address and Login IDs. Descope also logs other various updates, deletes, or create events within the UI, such as management key, access key, or tenant alteration.

Descope supports streaming your audit trail to a third-party service, to learn more about this concept, review the Audit Trail Streaming knowledge base article.

You can search the Descope audit trail via the Descope SDK which is shown below, or you can utilize the Descope console or the Search Audit API endpoint.

Searching the Descope Audit Trail via SDK

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Search Audits

// Args:
//    searchOptions: (AuditSearchOptions): A completed descope structure with the desired audit search options.
 
const searchOptions = {
  userIDs: ["xxxxxx"],
  actions: ["LoginSucceed"],
  excludedActions: null, // List of actions to exclude
  // from: time.Tim, // Retrieve records newer than given time. Limited to no older than 30 days.
  // to: time.Time,  // Retrieve records older than given time.
  devices: null, // List of devices to filter by. Current devices supported are "Bot"/"Mobile"/"Desktop"/"Tablet"/"Unknown"
  methods: null, // List of methods to filter by. Current auth methods are "otp"/"totp"/"magiclink"/"oauth"/"saml"/"password"
  geos: null, // List of geos to filter by. Geo is currently country code like "US", "IL", etc.
  remoteAddresses: null, // List of remote addresses to filter by
  loginIDs: null, // List of login IDs to filter by
  tenants: null, // List of tenants to filter by
  noTenants: true, // Should audits without any tenants always be included
  // text: "John" // Free text search across all fields
}
 
const resp = await descopeClient.management.audit.search(searchOptions)
if (!resp.ok) {
  console.log("Failed to search audits.")
}
else {
  console.log("Successfully searched audits.")
  console.log(resp)
}

User Update Audit Detail

It's crucial to see user configuration changes in your audit trail. To help you track these changes, Descope logs the new values of the changed UserModified actions. Below is an example of the detail provided within the audit trail of a UserModified action with various changes.

{
  "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"
  }
}

Was this helpful?