Skip to content

Troubleshooting

Use this guide to triage common SigID integration and tenant operation issues.

Check:

  • client_id belongs to the expected tenant application
  • redirect_uri exactly matches a registered redirect URI
  • response_type=code
  • code_challenge_method=S256
  • scope contains openid when OIDC claims are expected
  • tenant login methods are enabled
  • user is not suspended in the tenant
  • SSO enforcement is not routing the user to a misconfigured provider

Common causes:

Symptom Likely cause
Invalid redirect URI URI mismatch, trailing slash difference, wrong environment
Missing login option Sign-in method disabled for tenant or organization
SSO loop Provider redirect URI or issuer metadata mismatch
Silent login fails prompt=none requires an existing session and no interaction

Callback returns an error

Check:

  • state matches the value your app created
  • authorization code is exchanged only once
  • token exchange uses the same redirect_uri
  • backend uses the original code_verifier
  • client authentication method matches the application type

Treat callback errors as user-visible states. Show a retry path and log the request ID, tenant, client ID, and error code without logging tokens.

Token validation fails

Check:

  • issuer matches discovery metadata
  • audience matches your API
  • JWKS cache is current
  • token has not expired
  • server clock is synchronized
  • required scope is present
  • tenant in token matches requested tenant resource
  • DPoP proof is present when required

Fail closed. Do not bypass token validation during incidents; use introspection from a trusted backend if local validation is temporarily unavailable.

User can sign in but cannot access the app

Check:

  • tenant user status is active
  • organization membership is present when required
  • role assignment includes the needed permissions
  • application requested the needed scopes
  • backend checks tenant-local subject, not email
  • policy does not require MFA or fresh login
  • suspended or removed membership has not been cached by your app

Enterprise SSO fails

Check:

  • organization domain is verified
  • provider issuer, authorization endpoint, token endpoint, UserInfo endpoint, and JWKS URI are correct
  • provider client ID and secret are current
  • redirect URI is registered with the provider
  • provider is returning required claims
  • group or role mapping still matches provider output
  • a break-glass administrator remains available

Roll out enforcement gradually and monitor failed SSO events.

Webhooks fail

Check:

  • subscription is active
  • event type is selected
  • receiver URL is HTTPS and reachable
  • receiver returns 2xx after accepting the event
  • receiver verifies signatures against the raw request body using the full canonical string format
  • receiver allows the SigID request timeout
  • duplicate delivery IDs are handled idempotently

For the full list of delivery headers and signature verification steps, see Webhooks And Events.

Common receiver mistakes:

Mistake Fix
Re-serializing JSON before verification Verify the raw body
Comparing signatures with normal string equality Use constant-time comparison
Processing before deduplication Store delivery ID first
Returning 2xx before persistence Return success only after safe acceptance
Logging full payloads Redact sensitive fields
Ignoring the timestamp or max-age Reject deliveries where now - timestamp exceeds X-SigID-Signature-Max-Age
Not checking the suite header Reject if X-SigID-Signature-Suite is missing or unrecognized

Agent access is denied

Check:

  • agent is active
  • anchor is verified and not revoked
  • signing key is active
  • requested scope is allowed for the agent
  • delegation exists and has not expired
  • user consent covers the requested action
  • MCP server audience matches the token
  • policy does not require human approval or MFA step-up

For incidents, suspend the agent and revoke delegations before investigating downstream side effects.

Organization access is wrong

Check:

  • active organization context
  • membership role
  • organization owner/admin assignment
  • domain verification status
  • SSO group mapping
  • recent directory sync events
  • cached application authorization state

If a directory removed a user, confirm whether your tenant policy suspends or removes membership.

Useful evidence

Collect:

  • tenant slug or ID
  • application client ID
  • user tenant-local subject
  • organization ID
  • request ID
  • webhook delivery ID
  • event type
  • timestamp with timezone
  • sanitized error response
  • audit log entries around the failure

Do not collect raw access tokens, refresh tokens, webhook secrets, client secrets, MFA codes, or recovery codes in support tickets.

Related by summary, tags, categories, and content
Applications And OAuth Integrate applications with SigID using OAuth 2.1, OpenID Connect, PKCE, token validation, consent, and tenant-scoped subjects. oauth oidc pkce Security Review tenant and end-user security controls for OAuth tokens, secrets, MFA, consent, agents, wallets, webhooks, and incidents. security checklist token validation mfa Quickstarts Follow production-shaped quickstarts for tenant creation, hosted login, OAuth integration, organizations, agents, and webhooks. quickstart tenant setup oauth