The Search Atlas WordPress Plugin automatically handles API key configuration, plugin authentication, OTTO Pixel UUID injection, Server-Side Rendering (SSR), and OTTO communication with your site. If auto-configuration fails, use this guide to manually configure credentials and resolve common OTTO status errors.
⚠️ When to Use This Guide
Use this guide only if you have installed the Search Atlas WordPress Plugin and see one of the errors below. Match the message to where it appears in the UI.
In your OTTO dashboard:
- "OTTO Not Detected"
- "OTTO is disengaged" — only follow this guide if OTTO disengaged on its own without user action. If your team disengaged it intentionally, re-engage from the OTTO dashboard and monitor for re-deployment.
- Missing deployed fixes or no crawl data
In the WordPress plugin panel:
- "Your script is using an incorrect UUID"
- "Incorrect site token"
- "API key could not be verified"
In OTTO diagnostics / scan results:
- "Duplicate Installation Detected" — if OTTO shows as installed but project UUIDs do not match, this may be a known platform bug (WP-343) rather than a true duplicate. Open a support ticket with your project UUID and site URL for engineering review (see Section 2).
- Pixel Not Detected
Note: Do not use this guide if your installation method is manual script, GTM, Shopify, GHL, Cloudflare Worker, or any other non-WordPress method.
🛠️ 1. Confirm the Plugin Is Installed Correctly
✔ Step 1 — Activate the Plugin
Go to WordPress → Plugins.
Search for Search Atlas SEO – Premier SEO Plugin.
Confirm the status shows Active. If not, click Activate.
✔ Step 2 — Verify Authentication
Go to WordPress → Search Atlas → Settings.
Confirm all four of the following are present:
- Green banner: Authentication Successful
- Search Atlas API Key: auto-filled
- Plugin Auth Token: auto-filled
- OTTO Pixel UUID: auto-filled
If any field is blank, click Connect to Search Atlas and complete authentication again.
⚠️ Known issue (AIAGENT-1905 — awaiting release): If Atlas Brain shows authentication status as PENDING but the WordPress plugin panel shows Authenticated, this is a known display mismatch. Do not re-enter or reset your credentials — re-authenticating repeatedly can break a working setup. Contact support and reference AIAGENT-1905 (include screenshots of both the plugin panel and the OTTO dashboard / Atlas Brain status) to confirm your actual authentication state.
⚠️ "API key could not be verified" error — Two separate values are required, and they are not interchangeable:
- SearchAtlas API Key — a 32-character alphanumeric code found under Settings → API Keys in your Search Atlas dashboard.
- Site Token — found in OTTO → Settings.
Paste each value into its respective field in the WordPress plugin panel. Entering the wrong value in either field (for example, a license key, account password, or swapping the API Key and Site Token) triggers this error.
⚠️ If credentials are confirmed correct and the error persists, this may be a known platform-level bug (ref: WP-331). Open a support ticket with your site URL, the last 4 characters of your API Key, and your Site Token so engineering can investigate.
When both credentials are confirmed, the green Authentication Successful banner appears and all fields auto-fill.
🗺️ 2. Verify OTTO Pixel Settings (Critical)
Go to WordPress Admin → Search Atlas → Settings.
✔ Confirm the OTTO Pixel UUID Is Populated
If the UUID field is blank, click Connect to Search Atlas again to re-authenticate and populate it automatically.
⚠️ Known issue (WP-343 — awaiting release): A platform bug can cause OTTO to display as Installed even when the project UUID does not match the UUID detected on the site. If you have confirmed the UUID values are mismatched but OTTO still shows as Installed, this is a bug — contact support rather than continuing to troubleshoot locally.
✔ Disable "OTTO for Logged-in Users"
Toggle Disable OTTO for Logged-in Users to OFF during troubleshooting. If this is ON, OTTO will not load while you are logged in, producing false negatives in your tests.
✔ Disable Schema Markup (Optional)
✔ Enable Meta Description (Optional)
Important: Do not add any OTTO Pixel script manually to your theme, header.php, or GTM. When the plugin is active, no manual pixel injection is needed — the plugin handles it automatically.
⚠️ If OTTO is adding unexpected content to your site (e.g., unwanted heading text or other injected content), go to OTTO → Deployed Fixes, identify the responsible fix by name (e.g., Heading Length), and click Undeploy. The injected content will be removed immediately.
When all required settings are confirmed, OTTO can deploy fixes and the pixel UUID will match your OTTO project.
✅ 3. Confirm the Pixel Actually Loads (No Cache Interference)
✔ Step 1 — Log Out of WordPress
The pixel does not load for logged-in users when the Disable OTTO for Logged-in Users toggle is enabled. Log out before testing to avoid a false negative.
✔ Step 2 — Inspect the Page Source
Open your homepage, then right-click and select View Page Source.
Press Ctrl+F (Windows) or Cmd+F (Mac) and search for:
sa-dynamic-optimization
- Found: The pixel is loading correctly. No further action needed in this section.
- Not found: Proceed to Sections 4 and 5 to resolve firewall blocks and cache interference.
⚠️ 4. Whitelist the Search Atlas Crawler
If your firewall or bot-protection plugin blocks the Search Atlas crawler, OTTO will show "Not Installed" even when the plugin is configured correctly. Whitelist the crawler in each active security tool below.
Cloudflare
Go to Dashboard → Security → Bots and turn OFF:
- Bot Fight Mode
- Super Bot Fight Mode
WordFence
Go to WordPress Admin → WordFence → Firewall → Options.
Set Web Application Firewall Status to Disabled (temporary).
Stop Bad Bots
Go to WP Admin → Block Bad Bots → Settings.
Disable Block All Bots, or add the following to the whitelist:
Search Atlas Bot (https://www.searchatlas.com/)
Blackhole for Bad Bots
Add the following to the whitelist:
Search Atlas Bot (https://www.searchatlas.com/)
Shield Security
Go to WP Admin → Shield → IP Rules → User Agent Rules and add to the whitelist:
Search Atlas Bot (https://www.searchatlas.com/)
After whitelisting the crawler in all active security tools, trigger a new OTTO scan to confirm the crawler can now reach your site.
🔵 5. Clear ALL WordPress Caches
Caching is the most common cause of pixel dete
🎯 Once authentication is confirmed, the OTTO pixel is detected, and your crawler is whitelisted, OTTO should be fully operational and deploying fixes to your site. If errors persist after completing every section, contact Search Atlas support with your site URL, project UUID, and screenshots of all error messages for engineering review.