Skip to content

Get started

Last updated View as MarkdownAgent setup

Use this guide to onboard your own IP prefixes to Cloudflare. Before you begin, you must contact your account team to confirm that your contract includes BYOIP and that your account has the required service configuration.

Review the BYOIP Service-Specific Terms ↗︎ before you onboard a prefix.

Before you begin

You must meet all of the following requirements. Cloudflare cannot onboard your prefix if any registration, IRR, RPKI, or ownership validation check fails.

1. Add and validate your prefix

Add your prefix

  1. Use the Add Prefix endpoint to add the prefix to the Cloudflare account that will own it.

    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes" --request POST --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" --json '{"cidr":"203.0.113.0/24","asn":13335,"delegate_loa_creation":true}'
    Responsejson
    {
  "result": {
    "id": "72823e95d6c64d48a8111fec81179816",
    "created_at": "2025-02-25T00:34:11.423722Z",
    "modified_at": "2025-02-25T00:34:11.423722Z",
    "cidr": "203.0.113.0/24",
    "account_id": "654c5f71c324478cc9f68d60065d4620",
    "description": "",
    "approved": "P",
    "on_demand_enabled": false,
    "on_demand_locked": false,
    "advertised": null,
    "advertised_modified_at": null,
    "loa_document_id": "b9ff4afe312246a8b2e7324d98f40b23",
    "asn": 13335,
    "ownership_validation_token": "<OWNERSHIP_VALIDATION_TOKEN>",
    "delegate_loa_creation": true,
    "irr_validation_state": "pending",
    "rpki_validation_state": "pending",
    "ownership_validation_state": "pending"
  }
}

  2. Save the prefix id and ownership_validation_token from the response. You will use them in later steps.

Validate prefix ownership

Prove ownership by adding the validation token to either your IRR record or reverse DNS. You only need to use one of these methods.

  1. Copy the ownership_validation_token returned when you added the prefix.

  2. Add the following value to a description or remarks field in the matching IRR route or route6 object. Replace <OWNERSHIP_VALIDATION_TOKEN> with your token.

    cf-validation: <OWNERSHIP_VALIDATION_TOKEN>

    The process for updating an IRR object depends on the registry. Refer to IRR best practices for more information.

  1. Determine which reverse DNS zones are required for your prefix. IPv4 reverse DNS delegations commonly align on octet boundaries, and IPv6 delegations align on nibble boundaries. A prefix that does not align with the next boundary must be divided into smaller reverse zones.

    Examples

    Use the following formula to determine the number of zones at the next delegation boundary:

    2^(next boundary - current prefix length)

    The IPv4 prefix 192.0.2.0/23 requires two /24 reverse zones: one for 192.0.2.0/24 and one for 192.0.3.0/24.

    The IPv6 prefix 2001:db8::/34 requires four /36 reverse zones: 2001:db8::/36, 2001:db8:1000::/36, 2001:db8:2000::/36, and 2001:db8:3000::/36.

  2. Create the required reverse DNS zones. If you use Cloudflare for authoritative DNS, refer to Set up a reverse DNS zone. Otherwise, follow your DNS provider's instructions.

  3. In each reverse zone, create a TXT record named cf-validation whose value is the ownership validation token.

    cf-validation.<REVERSE_ZONE> IN TXT "<OWNERSHIP_VALIDATION_TOKEN>"

  4. At your RIR, delegate the reverse zones to the authoritative nameservers that host them.

After publishing the validation token, use the Validate Prefix endpoint to trigger the prefix validation checks:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/validate" --request POST --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Use the Prefix Details endpoint to monitor validation. When the IRR, RPKI, and ownership checks pass, the approved field for the prefix returns "V". You can then remove the ownership validation token and proceed to create service bindings.

If validation fails, refer to Troubleshoot prefix validation, correct the reported issues, and trigger validation again.

Optional: Delegate the prefix

You can allow another Cloudflare account to use all or part of the prefix. Refer to Prefix delegations for details.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/delegations" --request POST --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" --json '{"cidr":"<IP_PREFIX_TO_DELEGATE>","delegated_account_id":"<DELEGATED_ACCOUNT_ID>"}'

2. Create service bindings

Service bindings determine which Cloudflare service receives traffic destined for an IP address in your prefix. Configure service bindings while the prefix is withdrawn.

Create the default service binding

Each prefix requires a default service binding that covers the entire prefix. Cloudflare uses this binding for any IP address that does not have a more-specific binding.

  1. Use the List Services endpoint to find the id of the service that will receive traffic by default.

  2. If necessary, use the List Prefixes endpoint to find the prefix id.

  3. Use the Create Service Binding endpoint to bind the entire prefix to the default service.

    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bindings" --request POST --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" --json '{"cidr":"203.0.113.0/24","service_id":"<DEFAULT_SERVICE_ID>"}'

Optional: Create more-specific service bindings

Create more-specific bindings to send selected addresses in the prefix to a different service, such as CDN or Spectrum. Refer to Service bindings for service-specific configuration requirements.

Cloudflare recommends grouping contiguous IP addresses into the largest appropriate CIDR instead of creating a separate binding for each address.

Example

Suppose 203.0.113.0/24 uses Spectrum by default, but addresses 203.0.113.16 through 203.0.113.23 must use CDN. These eight contiguous addresses form 203.0.113.16/29, so you can create one CDN binding for that CIDR.

Use the Create Service Binding endpoint to create the more-specific binding.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bindings" --request POST --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" --json '{"cidr":"203.0.113.16/29","service_id":"<SERVICE_ID>"}'

The initial provisioning state in the response is provisioning:

Responsejson
{
	"errors": [],
	"messages": [],
	"success": true,
	"result": {
		"cidr": "203.0.113.16/29",
		"id": "<SERVICE_BINDING_ID>",
		"provisioning": {
			"state": "provisioning"
		},
		"service_id": "<SERVICE_ID>",
		"service_name": "<SERVICE_NAME>"
	}
}

Creating or deleting a service binding takes four to six hours to propagate across Cloudflare's network. Use the Get Service Binding endpoint to monitor its status. Wait until all bindings are active before you advertise the BGP prefix.

3. Advertise the BGP prefix

Cloudflare creates the BGP prefix in a withdrawn state. While it is withdrawn, you can configure service bindings, but you cannot create an address map that uses its IP addresses.

After the default binding and any more-specific bindings are active, advertise the prefix:

  1. Use the List BGP Prefixes endpoint to get the BGP prefix id.

  2. Use the Update BGP Prefix endpoint to advertise the prefix.

    curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bgp/prefixes/$BGP_PREFIX_ID" --request PATCH --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" --json '{"on_demand":{"advertised":true}}'

Confirm that the prefix is advertised before proceeding. Route propagation across the global Internet can take several minutes.

4. Configure address maps for CDN

If the prefix will be used for CDN ingress, create an address map after the BGP prefix is advertised. An address map determines which BYOIP addresses Cloudflare returns for proxied DNS records in an account or zone.

  1. Confirm that the BGP prefix is advertised and that the CDN service binding is active.

  2. Create an address map containing the BYOIP addresses that Cloudflare should return.

  3. Associate the address map with the appropriate account or zones.

  4. Verify that DNS queries for proxied hostnames return the expected BYOIP addresses before moving production traffic.

Address maps are not required for prefixes used only with services that do not use Cloudflare's proxied DNS responses. For more information, refer to About address maps.

Was this helpful?