Skip to content
Cloudflare Docs

Get started

To use your own IP addresses with Cloudflare, please check with your account team to confirm your contract covers this functionality. You will need to configure settings specific to the services you want to use, as well as meet some standard requirements for all BYOIP customers.

Once your account configurations are in place, consider the sections below to learn how to set up your BYOIP prefixes. Also make sure to review the BYOIP Service-Specific Terms ↗.

Before you begin

1. Set up your prefixes

Add your prefix

Use the Add Prefix endpoint to create a prefix in the Cloudflare account that should own the BYOIP prefix.

Add Prefix
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes" \
  --request POST \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "cidr": "203.0.113.0/24",
    "asn": 13335,
    "delegate_loa_creation": true
  }'
Response
 "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",
  }
  1. Take note of the id assigned to the prefix you added. It will be used in future steps.

Validate prefix ownership

Validate prefix ownership using one of the following methods:

  1. Copy the ownership_validation_token returned by the API call.
  2. On the IRR record of the prefix you are onboarding, add the following string in either a description or remarks field. Replace <OWNERSHIP_VALIDATION_TOKEN> by the actual token you copied in the previous step.
cf-validation: <OWNERSHIP_VALIDATION_TOKEN>

Once the ownership validation is successful, you can remove the token.

When all validations pass - RPKI, IRR, and ownership - the approved field in your prefix will return "V". This means you can proceed to create IP address service bindings1.

If needed, you can use the Prefix Details endpoint to check if any issues were found during validation. If so, proceed with the necessary changes and make a request to restart validation. Refer to Prefix validation checks for details.

(Optional) Delegate your BYOIP prefixes

You can allow other accounts to use part or all of your BYOIP prefix. Refer to Prefix delegations for details.

Required API token permissions

 At least one of the following token permissions is required:
  • IP Prefixes: Write
Create Prefix Delegation
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/delegations" \
  --request POST \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "cidr": "<IP_PREFIX_TO_DELEGATE>",
    "delegated_account_id": "<ACCOUNT_ID>"
  }'

2. Create service bindings

In IP address management, service bindings map the traffic destined for a given IP address to the Cloudflare service that it should be routed through.

Default service binding

When you onboard your IP prefixes to Cloudflare, there must be one service binding that spans across your entire prefix. Traffic destined for a given IP address will be routed to this service by default. You can also configure additional service bindings as described in the next step.

  1. Make a GET request to the List Services endpoint and take note of the id associated with the service you want to use.
  2. (Optional) If needed, use the List Prefixes endpoint to get or confirm the id associated with your prefix.
  3. Make a POST request to the Create service binding endpoint, indicating the entire BYOIP prefix that you are onboarding and the service that should be used for your default binding.

Required API token permissions

 At least one of the following token permissions is required:
  • IP Prefixes: Write
Create Service Binding
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bindings" \
  --request POST \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "cidr": "203.0.113.0/24",
    "service_id": "<DEFAULT_SERVICE>"
  }'

A corresponding BGP prefix will be created automatically. Allow five hours before you advertise the prefix.

(Optional) Additional bindings

If you want to selectively route traffic on a per-IP address basis to CDN or Spectrum, you can create additional service bindings.

  1. Plan for what IP(s) will get the additional binding. Cloudflare strongly recommends implementing service bindings through an aggregated CIDR block, as it is more efficient than adding discrete bindings for non-contiguous CIDR blocks.

Example

Spectrum protected prefix: 203.0.113.0/24

IPs to upgrade to CDN:

203.0.113.16
203.0.113.17
203.0.113.18
203.0.113.19
203.0.113.20
203.0.113.21
203.0.113.22
203.0.113.23

Add one discrete CDN service binding for 203.0.113.16 with a /29 netmask.

  1. Make a POST request to the Create service binding endpoint, indicating the IP address you want to bind to the CDN or Spectrum. Specify the corresponding network mask as needed.

Required API token permissions

 At least one of the following token permissions is required:
  • IP Prefixes: Write
Create Service Binding
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bindings" \
  --request POST \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "cidr": "203.0.113.16/29",
    "service_id": "<SERVICE_ID>"
  }'

In the response body, the initial provisioning state should be provisioning.

   {
     "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>"
     }
   }

Once a service binding is created (or deleted), it will take four to six hours to propagate across Cloudflare's global network.

3. Advertise the BGP prefix

Once automatically created (following step 2), BGP prefixes are initially withdrawn. After all your configurations are in place - including address maps2 if you will use CDN service -, proceed to advertise the BGP route for your prefix.

  1. Use the Update BGP prefix endpoint to start the advertisement.

Required API token permissions

 At least one of the following token permissions is required:
  • Magic Transit Write
  • IP Prefixes: Write
  • IP Prefixes: BGP On Demand Write
Update BGP Prefix
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/addressing/prefixes/$PREFIX_ID/bgp/prefixes/$BGP_PREFIX_ID" \
  --request PATCH \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "on_demand": {
        "advertised": true
    }
  }'

Footnotes

  1. Mappings that control through which pipeline traffic destined for a given IP address will be routed. ↩

  2. Mappings that specify which IP addresses should be used when Cloudflare responds to DNS queries for proxied hostnames. ↩