Audit with Management SDKs

You can search the Descope audit trail and emit custom audit events from your backend using the Management SDK or the Search Audit and Create Audit Event API endpoints.

For filtering in the Descope Console, see Filtering Audit Events.

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)
}

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)
}

All parameters are optional. Combine them to build precise queries.

Parameter	Type	Description
`actions`	`string[]`	Filter to specific event actions (maps 1:1 to event types). See Audit Events for valid values.
`excludedActions`	`string[]`	Exclude specific event actions from results.
`userIDs`	`string[]`	Filter by Descope User ID(s).
`loginIDs`	`string[]`	Filter by Login ID(s) (e.g., email address, phone number).
`from`	`timestamp`	Return events newer than this time. Cannot be older than 30 days.
`to`	`timestamp`	Return events older than this time.
`devices`	`string[]`	Filter by device type: `"Bot"`, `"Mobile"`, `"Desktop"`, `"Tablet"`, `"Unknown"`.
`methods`	`string[]`	Filter by authentication method: `"otp"`, `"totp"`, `"magiclink"`, `"oauth"`, `"saml"`, `"password"`.
`geos`	`string[]`	Filter by country code, e.g. `"US"`, `"IL"`.
`remoteAddresses`	`string[]`	Filter by originating IP address(es).
`tenants`	`string[]`	Filter by tenant ID(s).
`noTenants`	`boolean`	When `true`, always includes events with no associated tenant alongside tenant-scoped results.
`text`	`string`	Free-text search across all audit fields.

Example: failed logins for a user (last 7 days)

const searchOptions = {
  userIDs: ["U2abc123xyz"],
  actions: ["LoginFailed"],
  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
}

const resp = await descopeClient.management.audit.search(searchOptions)

Create Audit Event

Beyond the events Descope logs automatically, you can emit custom audit rows from your backend. See Creating Custom Audit Events on the Audit Events reference.

// Args:
//    auditOptions: (AuditCreateOptions): A completed descope structure with the desired audit creation options.

const auditOptions = {
  userId: "xxxxxx", // Optional audit user ID
  action: "LoginSucceed", // The action that was performed.
  type: "info", // Choose from three severity levels: info, warn, or error
  actorId: "xxxxxx", // The user that performed the action
  tenantId: "xxxxxx", // The tenant that the action was performed in
  data: { // Optional additional data to include in the audit event
    key1: "value1",
    key2: "value2"
  }
}

await descopeClient.management.audit.createEvent(auditOptions)

Was this helpful?