Skip to main content

Connect a Cloudflare account

Connecting Cloudflare lets Retrievy audit your zones, DNS records, WAF rules, access policies, R2 buckets, and account settings. Findings flow into the Command Center and feed your Retrievy Index the moment the first scan lands.

Cloudflare uses API tokens, which is the recommended authentication model for any third-party integration. Tokens are scoped at creation time, revocable instantly, and don't need rotation unless compromised. There's no OAuth Quick Connect for Cloudflare today.

Before you start​

You need:

  • A Cloudflare account where you can create API tokens.
  • A Retrievy workspace with CSPM enabled (every plan).
  • The manage-cloud-accounts permission in Retrievy.
  • One free data-source slot on your plan.

Step 1. Create a scoped API token in Cloudflare​

In the Cloudflare dashboard:

  1. Open your profile menu (top-right) → My Profile → API Tokens (left sidebar).
  2. Click Create Token.
  3. Cloudflare offers templates. The closest fit is Read all resources under the General templates section. Click Use template next to it.
  4. The template pre-fills the right permissions. Review and tweak if you want to scope tighter. The minimum permission set Retrievy needs:
PermissionScopeWhy Retrievy needs it
Account Settings: ReadAll accounts (or specific account)Reads account-level audit log and access policy settings.
Zone Settings: ReadAll zonesReads per-zone configuration (SSL/TLS, security level, etc.).
Zone: ReadAll zonesEnumerates zones in the account.
DNS: ReadAll zonesReads DNS records for misconfiguration checks (open SPF, missing DMARC, etc.).
Access: Apps and Policies: ReadAll accountsReads Cloudflare Access policies if you use Zero Trust.
Workers Scripts: ReadAll accountsAudits Workers deployments if you use them.
  1. Account Resources: pick Include → All accounts (or just the specific account you want scanned).
  2. Zone Resources: pick Include → All zones from an account → pick your account.
  3. Client IP Address Filtering: optional. If you want to lock the token to specific IPs, add Retrievy's egress IPs (contact support for the current list).
  4. TTL: optional. Tokens default to never expiring. If your security policy requires an expiry, pick a date (Retrievy reminds you 30 days before).
  5. Click Continue to summary → Create Token.
  6. Cloudflare shows the token value once. Copy it now; once you close the page, it can't be retrieved.
caution

The API token is a long-lived read-only credential for your Cloudflare account. Treat it like a password. Rotate it from the API Tokens page if you suspect it was exposed, and revoke it instantly from the same page when you remove the account from Retrievy.

Step 2. (Optional) Note your Account ID​

If you have multiple Cloudflare accounts under the same login, providing the Account ID in step 3 tells Retrievy which one to scan. To find it:

  1. In the Cloudflare dashboard, open any zone under the account you want.
  2. Scroll to API in the right sidebar (or look at the URL — the 32-character hex string after /accounts/ is the account ID).
  3. Copy the Account ID.

You can skip this if you only have one account on your login; Retrievy auto-detects it.

Step 3. Add the account in Retrievy​

In Retrievy:

  1. Open Settings → Cloud Integrations → Add Cloud Account.
  2. On the IDENTIFY TARGET step, pick Cloudflare from the provider tiles. Click Next.
  3. The INGEST CREDENTIALS step shows two fields:
FieldWhat to paste
API TokenThe token from step 1. Masked.
Account IDOptional. The 32-character hex ID from step 2. Leave blank to auto-detect.

  1. Click Next. Retrievy validates the token format (it must be a 40-character alphanumeric string) and saves the account.

  2. On the final step, click Finish. The first scan queues automatically.

Step 4. Watch the first scan​

The account appears in Settings → Cloud Integrations with a Scanning... state. Cloudflare scans are quick (most accounts complete in under a minute) because the API is paginated efficiently and there are no per-region calls.

When the scan completes, findings start landing in the Command Center. Open the CSPM dashboard → filter by Cloudflare to see the per-provider view.

What Retrievy scans​

The Cloudflare CSPM module covers:

  • Account settings: audit log retention, 2FA enforcement, single sign-on, IP access rules.
  • Zone settings: TLS version, HSTS, certificate transparency monitoring, Always Use HTTPS, security level, browser integrity check.
  • DNS hygiene: missing SPF, missing DMARC, weak DMARC policies, dangling CNAMEs, public records that look like staging or dev environments.
  • WAF and security rules: rate limiting, managed ruleset enablement, custom rules effectiveness.
  • Cloudflare Access: policy gaps, identity-provider configuration, app exposure without auth.
  • R2 buckets: bucket-level public access, lifecycle and versioning settings.
  • Workers: published-script enumeration and secret-binding hygiene.

Findings carry CIS Cloudflare Foundations Benchmark mappings.

Connecting multiple Cloudflare accounts​

If you administer several Cloudflare accounts (for example, one per business unit), add them one by one in the wizard. Each account needs its own token (you can use the same token if it was scoped to All accounts, but most security teams prefer one token per account for blast-radius hygiene).

Each Cloudflare account counts as one data-source slot on your plan.

Rotating the token​

  1. In Cloudflare, My Profile → API Tokens → Roll on the token you want to rotate. Cloudflare generates a new value and shows it once.
  2. In Retrievy, open the Cloudflare account detail → Update credentials → paste the new token. Save.
  3. Cloudflare automatically invalidates the old token on roll, so there's no cleanup step on the Cloudflare side.

Revoking access​

  1. In Retrievy, Deactivate the account (pauses scans) or remove it entirely (releases the slot).
  2. In Cloudflare, My Profile → API Tokens → Delete on the token. The token stops working instantly.

Troubleshooting​

Symptom: Wizard rejects the token with Invalid API token format. → Fix: You probably pasted the Global API Key instead of an API token. The Global API key is your legacy account-wide credential and is not supported; Retrievy requires the newer scoped token model. Go back to My Profile → API Tokens and use the Create Token flow.

Symptom: First scan fails with Authentication failed. → Fix: The token was likely created with a TTL that already expired, or it was deleted from Cloudflare after pasting into Retrievy. Roll the token in Cloudflare and re-paste the new value in Retrievy.

Symptom: Scan succeeds but only Zone findings appear; Account findings are missing. → Fix: Your token was scoped to a zone, not the whole account. Re-create the token with Account Settings: Read included, and Account Resources set to Include all accounts (or the specific account).

Symptom: Scan succeeds but DNS records are missing. → Fix: Your token is missing DNS: Read. Edit the token in Cloudflare to add it, save, and re-trigger the scan.

Symptom: I get 403 Forbidden on Cloudflare Access checks. → Fix: You don't have Zero Trust enabled on the account, or you didn't include Access: Apps and Policies: Read in the token. If you don't use Cloudflare Access, ignore the warning — there's nothing to scan. If you do, add the permission and re-scan.

Symptom: I want to scan a single zone, not the whole account. → Fix: Create the token with Zone Resources scoped to that specific zone instead of all zones. Account-level findings will be skipped, but the targeted zone gets full coverage.