Errors and Troubleshooting

Audit

The Descope Audit Trail provides comprehensive logging of all security-relevant events within your Descope project. This guide explains how to access, search, and utilize the audit trail for security monitoring and compliance purposes.

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 as shown below, or you can utilize the Descope console or the Search Audit API endpoint.

For a full list of audit events that are logged, refer to our Audit Events doc.

Searching the Descope Audit Trail via SDK

Rate Limiting

Descope enforces a rate limit of 10 requests per minute for audit search operations.

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 client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain 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?

On this page