docs / troubleshooting
// TROUBLESHOOTING

Troubleshooting

Most issues fall into four categories. Find yours below. If none of these resolve it, email support@integritylayer.io with your tenant ID and dashboard error code.

01
Webhook not firing on new messages
Graph APIWebhooksGWS Pub/Sub
02
MFA challenge not arriving on sender's device
TOTPMFAEmail delivery
03
Too many false positives (normal emails quarantined)
Risk thresholdIntent classificationConfig
04
Graph API 403 Forbidden on quarantine action
Graph APIPermissionsError codes
WEBHOOK NOT FIRING ON NEW MESSAGES
Graph APIWebhooksGWS Pub/Sub
Symptoms
→ Emails pass through without quarantine
→ No events appear in the MSP dashboard log
→ Test email produces no Limbo event
Resolution Steps
01
Check subscription status
In MSP dashboard → Client → Webhook Status. Subscriptions expire after 3 days and auto-renew via cron. If renewal failed, click 'Re-register Webhooks'.
02
Verify admin consent (M365)
Azure Portal → Enterprise Apps → IntegrityLayer → API Permissions. Confirm 'Granted for [tenant]' appears next to all scopes. If missing, re-run admin consent.
03
Check Pub/Sub topic (GWS)
Google Cloud Console → Pub/Sub → Topics → integritylayer-{domain}. Topic must exist and IntegrityLayer service account must have 'Pub/Sub Publisher' role.
04
Firewall / outbound rules
Cloudflare Workers make outbound calls to graph.microsoft.com and gmail.googleapis.com. No inbound firewall changes are required on your end.
# Check subscription via Graph API
GET https://graph.microsoft.com/v1.0/subscriptions
# Look for: resource: 'me/mailFolders/inbox/messages'
# expirationDateTime must be > now()
MFA CHALLENGE NOT ARRIVING ON SENDER'S DEVICE
TOTPMFAEmail delivery
Symptoms
→ Email is quarantined but sender receives no notification
→ MFA challenge email lands in spam
→ Sender reports receiving notification but no TOTP prompt
Resolution Steps
01
Check sender's spam folder
MFA challenge emails are sent from no-reply@integritylayer.io. Whitelist this address in the client's mail security policy (Defender / SEG).
02
Verify MFA enrollment
Sender must have completed TOTP enrollment in their IntegrityLayer profile. Check: MSP Dashboard → Client → Users → [sender] → MFA Status = 'Enrolled'.
03
TOTP app sync
TOTP codes depend on device clock accuracy. If the sender's device clock is more than 30 seconds off, codes will fail. Check device time sync settings.
# Test MFA delivery manually
curl -X POST https://api.integritylayer.io/v1/mfa/test \
  -H 'Authorization: Bearer {api_key}' \
  -d '{"user": "cfo@client.com", "tenant": "client-id"}'
TOO MANY FALSE POSITIVES (NORMAL EMAILS QUARANTINED)
Risk thresholdIntent classificationConfig
Symptoms
→ Low-risk internal emails are being flagged
→ Users complaining about routine emails being blocked
→ Risk score appears high for benign messages
Resolution Steps
01
Raise the risk threshold
In config.yml, increase risk_threshold from 0.75 to 0.85 or 0.90. A higher threshold requires stronger signal before quarantine fires.
02
Narrow intent_classes
Remove broad classes like EXECUTIVE_REQUEST if your client doesn't need them. Stick to WIRE_TRANSFER and ROUTING_NUMBER for financial clients.
03
Add sender allowlist
High-frequency internal senders (e.g., automated systems, payroll software) can be added to the sender_allowlist in config to bypass classification.
# config.yml — raise threshold, narrow scope
risk_threshold: 0.85
intent_classes:
  - WIRE_TRANSFER
  - ROUTING_NUMBER
sender_allowlist:
  - payroll-system@client.com
  - billing@netsuite.com
GRAPH API 403 FORBIDDEN ON QUARANTINE ACTION
Graph APIPermissionsError codes
Symptoms
→ Error in dashboard: 'moveToQuarantine failed: 403 Forbidden'
→ Messages classified as HIGH_RISK but not quarantined
→ Audit log shows: QUARANTINE_FAILED
Resolution Steps
01
Re-grant admin consent
The Mail.ReadWrite Application permission may have been revoked. Go to Azure Portal → Enterprise Apps → API Permissions → Grant admin consent again.
02
Check conditional access policies
Some orgs have Conditional Access policies blocking service principal access to mailboxes. Exclude the IntegrityLayer enterprise app from these policies.
03
Verify hidden folder creation
On first deployment, IntegrityLayer creates a hidden 'IntegrityLayer_Quarantine' folder. If this failed, run: MSP Dashboard → Client → Repair → Recreate Quarantine Folder.
# Common error response
{
  "error": {
    "code": "ErrorAccessDenied",
    "message": "Access is denied. Check credentials and try again."
  }
}
# Fix: Re-grant admin consent in Azure Portal
← API Scopes Email Support →