Audit

The Descope Audit Trail logs security-relevant events across your Descope projects and company. Use it for monitoring, troubleshooting, and compliance.

How to Work With the Audit Trail

You can also open the Descope Console directly or call the Search Audit REST API.

For SCIM provisioning, Descope emits detailed audit rows (SCIMEvent) with request bodies, results, and field-level changes. See SCIM Audit Events.

Company-level Auditing

In addition to project-level events, Descope logs company-level events for actions taken across your Descope company: creating or deleting projects, managing management keys, and changing company settings. These events appear in the same audit table as project events so you have one place to review administrative activity.

To view only company-level events, open the Audit page in any project within your company and set the Level filter to Company. The same filter is available in the Search Audit API and Management SDKs.

For the full list of company-level events, see Company-level Audit Events. For where company-level configuration lives, see Company Settings.

Audit Details by Type

Some audit actions carry a structured Data payload with details about what changed. The sections below describe the fields logged for each of these action types.

User Update Audit Detail

Descope logs the new values on UserModified actions so you can see what changed on a user. Below is an example payload from the audit trail:

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

Role Association Audit Detail

Descope logs the UsersRolesAssociationsModified action whenever a user's role or tenant-role associations change, so you can see which users and roles were affected — and how — directly from the audit trail. It is generated when:

• Roles are assigned to users (add)
• Roles are removed from users (remove)
• Tenants and roles are assigned or removed together (add / remove)
• Roles are updated from SAML group mappings (set)
• A user's roles are bulk-set (set)
• Role or permission associations are recalculated after a group-mapping change (recalculate)

The Data section contains:

When a single user is affected, the event's User ID and Login IDs columns are also populated. Tenant-scoped changes list the affected tenants in the Tenants field.

Because these events now carry users_login_ids, you can filter them in the Search Audit API by externalIds (or by tenants).

Session Migration Audit Detail

Descope logs an audit event when an external session token is exchanged for a Descope session during session migration, on both success and failure:

• ExternalSessionMigrationSuccess - the exchange succeeded and a Descope session was issued.
• ExternalSessionMigrationFailure - the exchange failed. Logged as a Warning.

The failure event's Data section contains:

Failures include cases where no external authentication provider is configured on the project, no Descope user matched the identifier in the token, or Descope could not generate or validate the new session. Session migration does not create users just in time, so the user must already exist in Descope.