This article helps you resolve the error that appears when you paste a Cloudflare API token into Search Atlas. The error is almost always caused by one of a few specific token configuration issues — this guide walks you through each one so you can identify and fix the exact cause.
🔍 Common Causes
- Incorrect token permissions: The token was created without the required permissions for Search Atlas to connect.
- Token scope too narrow: The token is scoped to a specific zone (domain) but Search Atlas requires access to all zones, or vice versa.
- Extra whitespace: Copying the token from Cloudflare sometimes includes a leading or trailing space, which causes the validation to fail silently.
- Token was created as a Global API Key instead of an API Token: Search Atlas requires an API Token, not the Global API Key.
- Token has been revoked or expired: A previously working token may have been deleted or expired in Cloudflare.
🛠️ Step-by-Step
- Log in to your Cloudflare dashboard at dash.cloudflare.com and go to My Profile → API Tokens.
- Verify you are using an API Token, not the Global API Key. The Global API Key will not work. If you used the Global API Key, you must create a new API Token instead.
- Check the token's permissions. The token must include at minimum: Zone → DNS → Edit and Zone → Zone → Read. Read-only DNS access is not enough because OTTO writes DNS settings (it enables DNS proxy on DNS-only records). If these permissions are missing, click Edit on the token, add the missing permissions, and save.
- Check the token's Zone Resources scope. Set it to All zones unless Search Atlas documentation specifies a single-zone scope. Mismatched scope is a frequent cause of this error.
- Regenerate the token if you are unsure of its current state. In Cloudflare, click Roll (or delete and recreate it) to get a fresh token value.
- Copy the new token carefully. Click the copy icon in Cloudflare rather than selecting the text manually. This reduces the risk of copying extra whitespace characters.
- Paste the token into Search Atlas by opening your project settings and navigating to the Cloudflare integration field. Before saving, click inside the field and press Ctrl+A (or Cmd+A on Mac) to select all, then paste — this replaces any previous value fully rather than appending.
- Save the token and wait for the connection validation to complete.
✅ How to Confirm It Worked
After saving, Search Atlas will attempt to validate the token immediately. You will know the connection succeeded when:
- The error message disappears and is replaced by a green success indicator or a confirmation message such as "Token connected" or "Cloudflare connected successfully."
- Your Cloudflare zones or domain data become visible within the integration area — if zones were not populating before, they should now appear in a dropdown or list.
- No red error banner is shown after saving. If the red error persists even after following all steps, the token value itself is the issue — return to Cloudflare and create a brand-new token from scratch rather than reusing the same one.
If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.