Verify and Troubleshoot

After integration, verify the package install, access token provider, browser SDK, camera permission, and MonitorDog runtime API calls in order.

Quick checklist

• The browser app builds after npm install @monitordog/detector.
• Your server access token endpoint calls POST /v1/sdk/sessions.
• The access token request body is shaped as {"email":"user@example.com"}.
• The partner API key exists only in the server environment or secret manager.
• The SDK token response includes expires_in: 1800.
• MonitorDogDetector.init() does not call the server.
• detector.login({ email }) calls sessionTokenProvider({ email }).
• detector.start() begins model loading and camera permission request.
• The page runs over HTTPS or localhost and the user granted camera permission.
• Your app calls detector.stop() before detector.logout(), or uses detector.dispose() for forced cleanup.

SDK runtime API list

SDK token access is limited to the runtime API surface below.

Caller	Method	Path	Purpose
Customer server access token endpoint	POST	/v1/sdk/sessions	Issue an SDK access token by email
Browser SDK	GET	/v1/auth/sdk-model	Request encrypted detector model download info
Browser SDK	GET	/v1/account/me	Read the current SDK user
Browser SDK	GET	/v1/account/{uuid}/lock_policy	Read detection policy for the user
Browser SDK	POST	/v1/event	Record user activity and detector events
Browser SDK	POST	/v1/file/image	Upload event images

External SDK flow does not use refresh tokens, cookie refresh, password login, or MFA. The following endpoints belong to regular web or agent authentication flows and should not be called from SDK browser integration.

• /v1/auth
• /v1/auth/v2
• /v1/auth/cookie
• /v1/auth/mfa

Access token provider errors

401 or 403

The partner API key is usually missing or invalid.

Check these items:

• Server environment variable MONITORDOG_PARTNER_API_KEY is set.
• The MonitorDog API request includes Authorization: Bearer <partner API key>.
• The browser is not sending the partner API key directly.

Validation error

The current /v1/sdk/sessions body is email-only.

{
  "email": "user@example.com"
}

Sending account_uuid, external_user_id, external_session_id, or scopes causes a validation error.

Browser SDK errors

MonitorDog sessionTokenProvider is required for SDK login.

sessionTokenProvider is missing from MonitorDogDetector.init().

const detector = await MonitorDogDetector.init({
  apiBaseUrl: "https://api.monitor.dog/v1",
  sessionTokenProvider: async ({ email }) => {
    const response = await fetch("/api/monitordog/access-token", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email }),
    });

    return response.json();
  },
  onDetect: () => undefined,
});

The access token provider is not called after init

This is expected. init() only creates the detector and does not call the server. The access token provider is called by detector.login({ email }).

The token expires after 30 minutes

This is expected. SDK tokens are issued with expires_in: 1800. Before expiry, the SDK calls sessionTokenProvider({ email }) again. If the access token provider briefly fails while the current token is still valid, the SDK keeps using the existing token until it expires.

Camera errors

The permission prompt does not appear

• Confirm that the page is served over HTTPS or localhost.
• Check that camera permission is not blocked in browser site settings.
• Confirm that detector.login({ email }) and detector.start() have been called.

Camera permission denied

The user denied permission or browser policy blocked it. Allow camera access in site settings and call start() again.

Network tab order

1. detector.login({ email })
2. Customer endpoint /api/monitordog/access-token
3. Customer server call to MonitorDog POST /v1/sdk/sessions
4. Browser SDK login activity POST /v1/event
5. Browser SDK call to GET /v1/account/me
6. Browser SDK call to GET /v1/account/{uuid}/lock_policy
7. detector.start()
8. Browser SDK call to GET /v1/auth/sdk-model
9. On detection events, POST /v1/event and POST /v1/file/image

The partner API key should exist only in step 3, the server-to-server call.