Cloudflare

What your agents can doCopy Anchor Link

Helios uses a pinned version of Cloudflare's OpenAPI spec to look up REST endpoints. It attaches your token or OAuth credentials to API calls. Access depends on the token's permissions or the OAuth scopes you approve.

• Create, update, and delete DNS records, and change zone settings such as the security level
• Purge cached files after a deploy
• Inspect Workers, their versions and deployments, and set secrets
• Read and write Workers KV, manage R2 buckets, and query D1 databases
• Manage Access applications, WAF rules, and Cloudflare Tunnels

Agents can also produce and consume K2 stream records on each stream's own host, <STREAM_ID>.k2.cloudflarestorage.com. These calls need the full stream URL and an API token with the K2 Produce or K2 Consume permission. The GraphQL Analytics API is not included in endpoint lookup.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Every method needs your account ID. In the Cloudflare dashboard, open Workers & Pages and copy Account ID from Account Details.

Helios Cloudflare AppCopy Anchor Link

Connect through Helios's Cloudflare app. You don't need to create an app in Cloudflare.

1. In Helios, choose Helios Cloudflare App.
2. Enter Account ID. Turn on Admin access to also ask for the admin scopes.
3. Save, then approve access in Cloudflare. On the consent screen, choose the account whose ID you entered. If you leave it out, Helios doesn't save the connection and asks you to check the account ID.

Helios asks for every scope listed under Scopes Helios asks for below, and for the admin scopes when Admin access is on. Helios refreshes the access token when it expires. To change Admin access, edit it through Manage and connect again.

If Cloudflare refuses the authorization, an admin of your Cloudflare account may have turned off third-party apps. A Super Administrator can turn them on under Manage Account → Members → Settings → Public OAuth App access.

Cloudflare API TokenCopy Anchor Link

To create an account API token, you need the Super Administrator role or the API Token Provisioning capability. Any member can create a user token, which acts as that member. A token can only have permissions that its creator has.

1. In the Cloudflare dashboard, go to Manage account → Account API tokens and select Create Token. A user token from My Profile → API Tokens also works.
2. Select Create Custom Token and add permissions:
   • For full access, add every permission group under Account and Zone, each at its highest level, such as Edit. For a user token, also add the User permissions. Cloudflare lists them all in API token permissions.
   • Triggers need Notifications Edit. Alerts that Cloudflare limits to chosen zones also need Zone Read, and Pages alerts need Cloudflare Pages Read.
3. Under Zone Resources, include all zones from the account.
4. Select Continue to summary, then Create Token, and copy the token.
5. In Helios, choose Cloudflare API Token. Enter Account ID, paste the token into API Token, and save.

A token with fewer permissions still works for the endpoints those permissions cover. For user tokens, the connection test verifies token validity. Account access is checked when you call account endpoints or set up triggers. If the token expires or you roll it, enter the new one through Manage. If you add permissions for more alerts, save the connection again so Helios creates them.

Your own Cloudflare OAuth appCopy Anchor Link

To create an OAuth client, you need the Super Administrator, Administrator, or OAuth Client Write role.

1. In the Cloudflare dashboard, go to Manage Account → OAuth clients and select Create client.

2. Enter a client name. Set the response type to code, the grant types to authorization_code and refresh_token, and the token authentication method to client_secret_basic. With the refresh_token grant, Cloudflare adds the offline_access scope that Helios needs for a refresh token.

3. Add this redirect URL:

   Copy Text

   https://api.heliosapp.com/integrations/cloudflare/oauth_callback

4. Select Continue and add every scope in the table below. Helios asks for all of them, so the client needs every one. To let people decline some scopes on the consent screen, turn off Required for those scopes under Choose optional scopes.

5. If you'll turn on Admin access, also add account-api-tokens.write, account-settings.write, and scim-provisioning.write.

6. Select Create client and copy the Client ID and Client Secret. Cloudflare shows the secret only once.

7. In Helios, choose Your own Cloudflare OAuth app. Enter Account ID, Client ID, and Client Secret. Turn on Admin access to also ask for the admin scopes.

8. Save, then approve access in Cloudflare. Select the same account on the consent screen.

Admin access adds the scopes that manage the account itself: account-api-tokens.write creates and edits account API tokens, account-settings.write changes account settings and members, and scim-provisioning.write provisions members through SCIM. Cloudflare lets only a Super Administrator manage members and create account API tokens.

Cloudflare's list of OAuth scopes has no billing scopes, so OAuth connections can't read or change billing. Use an API token with the billing permissions for that.

A new client is private, so only members of your Cloudflare account can approve it. Helios refreshes the access token when it expires. If you rotate the client secret, enter the new one through Manage and connect again. To change Admin access, edit it through Manage and connect again.

TriggersCopy Anchor Link

Cloudflare can start a Workflow when it sends an alert. Webhooks are available on all Cloudflare plans. When you save the connection, Helios adds a webhook destination named Helios to your account. It attempts to create an alert named Helios: ... for each supported alert type your account offers. Deleting the connection removes the alerts and the destination.

This needs the Notifications Edit permission on the token, or the notifications.write scope for an OAuth app. Without it, agents still work, but no events reach Helios.

Each supported alert type has its own event:

• Zone matches the zone that the alert is about, chosen from your zones. It's optional. Alerts that aren't about a zone never match a zone filter.

Cloudflare offers each alert type only on some plans or with some products. The trigger picker marks the events your account doesn't offer as unavailable, with the reason.

Some alert types need filters. Helios uses the values listed by Cloudflare, known status values, or resources it can list in your account:

• Health check status alerts cover healthy and unhealthy changes.
• Pool enablement alerts cover pools being enabled and disabled.
• Pages alerts cover the projects Helios lists, both environments, and deployments that start, fail, or succeed.
• Alerts that require chosen zones cover the zones Helios lists in the account.

Helios reads up to 1,000 zones and 200 Pages projects when you save the connection. Save the connection again after you add a zone or a Pages project.

Some alert types need a value that only you can choose, such as a usage threshold, a budget, a service-level objective, a saved query, or a custom alert's SQL query. Helios can't create those alerts, so the trigger picker shows them as unavailable.

Some alerts send one notification when they start and another when they end. The payload's alert_event field is ALERT_STATE_EVENT_START or ALERT_STATE_EVENT_END, so say in the prompt which one the agent should act on.

Cloudflare doesn't sign notifications. It sends the destination's secret in the cf-webhook-auth header, and Helios compares it with the secret it generated for the connection. Notifications whose ts is more than an hour old are rejected.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Cloudflare rejected the token, or the token can't reach the account ID.
• The destination: in the Cloudflare dashboard, go to Alerts → Destinations. The Webhooks card should list Helios. Under Alerts → Overview, the Helios: ... alerts should be listed.
• A trigger:
  1. Add universal_ssl_event_type.sent to a workflow with no filters. Any event works if your account offers it.
  2. In Alerts → Overview, open the menu of the matching Helios: ... alert and choose Test. Cloudflare sends a test alert with sample data.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Cloudflare allows 1,200 API requests per five minutes for each user or account token, across the dashboard and the API. Accounts without a paid zone can have up to 100 webhook destinations. See Cloudflare's API rate limits and webhook setup.