Give Feedback

Cloud Firewalls API Reference

Validated on 19 Jun 2018 • Last edited on 23 Mar 2026

DigitalOcean Cloud Firewalls provide the ability to restrict network access to and from a Droplet allowing you to define which ports will accept inbound or outbound connections. By sending requests to the /v2/firewalls endpoint, you can list, create, or delete firewalls as well as modify access rules.

Base URL https://api.digitalocean.com

Endpoints

GET List All Firewalls POST Create a New Firewall GET Retrieve an Existing Firewall PUT Update a Firewall DELETE Delete a Firewall POST Add Droplets to a Firewall DELETE Remove Droplets from a Firewall POST Add Rules to a Firewall DELETE Remove Rules from a Firewall POST Add Tags to a Firewall DELETE Remove Tags from a Firewall

GET List All Firewalls

/v2/firewalls

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all of the firewalls available on your account, send a GET request to /v2/firewalls.

Query Parameters

per_page integer 1 – 200 optional

Example: 2

Number of items returned per page

Default: 20

page integer >= 1 optional

Example: 1

Which 'page' of paginated results to return.

Default: 1

Request: `/v2/firewalls`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/firewalls"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    opt := &godo.ListOptions{
        Page:    1,
        PerPage: 200,
    }

    firewalls, _, err := client.Firewalls.List(ctx, opt)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

firewalls = client.firewalls.all
firewalls.each

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.firewalls.list()

Responses

200

To list all of the firewalls available on your account, send a GET request to /v2/firewalls.

Firewalls responses will include only the resources that you are granted to see. Ensure that your API token includes all necessary <resource>:read permissions for requested firewall.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

firewalls array of object optional

Show child properties

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

links object optional

Show child properties

pages anyOf optional

One of:

Forward Links

last string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links

first string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "firewalls": [
    {
      "created_at": "2017-05-23T21:23:59Z",
      "droplet_ids": [
        8043964
      ],
      "id": "fb6045f1-cf1d-4ca3-bfac-18832663025b",
      "inbound_rules": [
        {
          "ports": "80",
          "protocol": "tcp",
          "sources": {
            "load_balancer_uids": [
              "4de7ac8b-495b-4884-9a69-1050c6793cd6"
            ]
          }
        },
        {
          "ports": "22",
          "protocol": "tcp",
          "sources": {
            "addresses": [
              "18.0.0.0/8"
            ],
            "tags": [
              "gateway"
            ]
          }
        }
      ],
      "name": "firewall",
      "outbound_rules": [
        {
          "destinations": {
            "addresses": [
              "0.0.0.0/0",
              "::/0"
            ]
          },
          "ports": "80",
          "protocol": "tcp"
        }
      ],
      "pending_changes": [],
      "status": "succeeded",
      "tags": []
    }
  ],
  "links": {},
  "meta": {
    "total": 1
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New Firewall

/v2/firewalls

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new firewall, send a POST request to /v2/firewalls. The request must contain at least one inbound or outbound access rule.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

Request: `/v2/firewalls`

Payload

Content type application/json

{
  "droplet_ids": [
    8043964
  ],
  "inbound_rules": [
    {
      "ports": "80",
      "protocol": "tcp",
      "sources": {
        "load_balancer_uids": [
          "4de7ac8b-495b-4884-9a69-1050c6793cd6"
        ]
      }
    },
    {
      "ports": "22",
      "protocol": "tcp",
      "sources": {
        "addresses": [
          "18.0.0.0/8"
        ],
        "tags": [
          "gateway"
        ]
      }
    }
  ],
  "name": "firewall",
  "outbound_rules": [
    {
      "destinations": {
        "addresses": [
          "0.0.0.0/0",
          "::/0"
        ]
      },
      "ports": "80",
      "protocol": "tcp"
    }
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"80","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": "22","sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"80","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964]}' \
  "https://api.digitalocean.com/v2/firewalls"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.FirewallRequest{
        Name: 'firewall',
        InboundRules: []godo.InboundRule{
            {
                Protocol: 'tcp',
                PortRange: '80',
                Sources: &godo.Sources{
                    LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'},
                },
            },
            {
                Protocol:  'tcp',
                PortRange: '22',
                Sources: &godo.Sources{
                    Addresses: []string{'18.0.0.0/8'},
                    Tags: []string{'gateway'},
                },
            },
        },
        OutboundRules: []godo.OutboundRule{
            {
                Protocol: 'tcp',
                PortRange: '80',
                Destinations: &godo.Destinations{
                    Addresses: []string{'0.0.0.0/0', '::/0'},
                },
            },
        },
        DropletIDs: []int{8043964},
    }

    firewall, req, err := client.Firewalls.Create(ctx, createRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

firewall = DropletKit::Firewall.new(
  name: 'firewall',
  inbound_rules: [
    DropletKit::FirewallInboundRule.new(
      protocol: 'tcp',
      ports: '80',
      sources: {
        load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']
      }
    ),
    DropletKit::FirewallInboundRule.new(
      protocol: 'tcp',
      ports: '22',
      sources: {
        tags: ['gateway'],
        addresses: ['18.0.0.0/8']
      }
    )
  ],
  outbound_rules: [
    DropletKit::FirewallOutboundRule.new(
      protocol: 'tcp',
      ports: '80',
      destinations: {
        addresses: ['0.0.0.0/0', '::/0'],
      }
    )
  ],
  droplet_ids: [8043964]
)

client.firewalls.create(firewall)

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "firewall",
  "inbound_rules": [
    {
      "protocol": "tcp",
      "ports": "80",
      "sources": {
        "load_balancer_uids": [
          "4de7ac8b-495b-4884-9a69-1050c6793cd6"
        ]
      }
    },
    {
      "protocol": "tcp",
      "ports": "22",
      "sources": {
        "tags": [
          "gateway"
        ],
        "addresses": [
          "18.0.0.0/8"
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "protocol": "tcp",
      "ports": "80",
      "destinations": {
        "addresses": [
          "0.0.0.0/0",
          "::/0"
        ]
      }
    }
  ],
  "droplet_ids": [
    8043964
  ]
}

resp = client.firewalls.create(body=req)

Responses

202

The response will be a JSON object with a firewall key. This will be set to an object containing the standard firewall attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

firewall object optional

Show child properties

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

202

{
  "firewall": {
    "created_at": "2017-05-23T21:24:00Z",
    "droplet_ids": [
      8043964
    ],
    "id": "bb4b2611-3d72-467b-8602-280330ecd65c",
    "inbound_rules": [
      {
        "ports": "80",
        "protocol": "tcp",
        "sources": {
          "load_balancer_uids": [
            "4de7ac8b-495b-4884-9a69-1050c6793cd6"
          ]
        }
      },
      {
        "ports": "22",
        "protocol": "tcp",
        "sources": {
          "addresses": [
            "18.0.0.0/8"
          ],
          "tags": [
            "gateway"
          ]
        }
      }
    ],
    "name": "firewall",
    "outbound_rules": [
      {
        "destinations": {
          "addresses": [
            "0.0.0.0/0",
            "::/0"
          ]
        },
        "ports": "80",
        "protocol": "tcp"
      }
    ],
    "pending_changes": [
      {
        "droplet_id": 8043964,
        "removing": false,
        "status": "waiting"
      }
    ],
    "status": "waiting",
    "tags": []
  }
}

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Firewall

/v2/firewalls/{firewall_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To show information about an existing firewall, send a GET request to /v2/firewalls/$FIREWALL_ID.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request: `/v2/firewalls/{firewall_id}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    firewall, _, err := client.Firewalls.Get(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c')
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.find(id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.firewalls.get(firewall_id= "as9di9d")

Responses

200

The response will be a JSON object with a firewall key. This will be set to an object containing the standard firewall attributes.

Firewalls responses will include only the resources that you are granted to see. Ensure that your API token includes all necessary <resource>:read permissions for requested firewall.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

firewall object optional

Show child properties

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "firewall": {
    "created_at": "2017-05-23T21:24:00Z",
    "droplet_ids": [
      8043964
    ],
    "id": "bb4b2611-3d72-467b-8602-280330ecd65c",
    "inbound_rules": [
      {
        "ports": "80",
        "protocol": "tcp",
        "sources": {
          "load_balancer_uids": [
            "4de7ac8b-495b-4884-9a69-1050c6793cd6"
          ]
        }
      },
      {
        "ports": "22",
        "protocol": "tcp",
        "sources": {
          "addresses": [
            "18.0.0.0/8"
          ],
          "tags": [
            "gateway"
          ]
        }
      }
    ],
    "name": "firewall",
    "outbound_rules": [
      {
        "destinations": {
          "addresses": [
            "0.0.0.0/0",
            "::/0"
          ]
        },
        "ports": "80",
        "protocol": "tcp"
      }
    ],
    "pending_changes": [],
    "status": "succeeded",
    "tags": []
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Firewall

/v2/firewalls/{firewall_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update the configuration of an existing firewall, send a PUT request to /v2/firewalls/$FIREWALL_ID. The request should contain a full representation of the firewall including existing attributes. Note that any attributes that are not provided will be reset to their default values.

You must have read access (e.g. droplet:read) to all resources attached to the firewall to successfully update the firewall.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

Request: `/v2/firewalls/{firewall_id}`

Payload

Content type application/json

{
  "droplet_ids": [
    8043964
  ],
  "inbound_rules": [
    {
      "ports": "8080",
      "protocol": "tcp",
      "sources": {
        "load_balancer_uids": [
          "4de7ac8b-495b-4884-9a69-1050c6793cd6"
        ]
      }
    },
    {
      "ports": "22",
      "protocol": "tcp",
      "sources": {
        "addresses": [
          "18.0.0.0/8"
        ],
        "tags": [
          "gateway"
        ]
      }
    }
  ],
  "name": "frontend-firewall",
  "outbound_rules": [
    {
      "destinations": {
        "addresses": [
          "0.0.0.0/0",
          "::/0"
        ]
      },
      "ports": "8080",
      "protocol": "tcp"
    }
  ],
  "tags": [
    "frontend"
  ]
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"8080","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": "22","sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"8080","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964],"tags":["frontend"]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    updateRequest := &godo.FirewallRequest{
        Name: 'firewall',
        InboundRules: []godo.InboundRule{
            {
                Protocol: 'tcp',
                PortRange: '8080',
                Sources: &godo.Sources{
                    LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'},
                },
            },
            {
                Protocol:  'tcp',
                PortRange: '22',
                Sources: &godo.Sources{
                    Addresses: []string{'18.0.0.0/8'},
                    Tags: []string{'gateway'},
                },
            },
        },
        OutboundRules: []godo.OutboundRule{
            {
                Protocol: 'tcp',
                PortRange: '8080',
                Destinations: &godo.Destinations{
                    Addresses: []string{'0.0.0.0/0', '::/0'},
                },
            },
        },
        DropletIDs: []int{8043964},
        Tags: []string{'frontend'}
    }

    firewall, req, err := client.Firewalls.Create(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', updateRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

firewall = DropletKit::Firewall.new(
  name: 'firewall',
  inbound_rules: [
    DropletKit::FirewallInboundRule.new(
      protocol: 'tcp',
      ports: '8080',
      sources: {
        load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']
      }
    ),
    DropletKit::FirewallInboundRule.new(
      protocol: 'tcp',
      ports: '22',
      sources: {
        tags: ['gateway'],
        addresses: ['18.0.0.0/8']
      }
    )
  ],
  outbound_rules: [
    DropletKit::FirewallOutboundRule.new(
      protocol: 'tcp',
      ports: '8080',
      destinations: {
        addresses: ['0.0.0.0/0', '::/0'],
      }
    )
  ],
  droplet_ids: [8043964],
  tags: ['frontend']
)

client.firewalls.update(firewall, id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "frontend-firewall",
  "inbound_rules": [
    {
      "protocol": "tcp",
      "ports": "8080",
      "sources": {
        "load_balancer_uids": [
          "4de7ac8b-495b-4884-9a69-1050c6793cd6"
        ]
      }
    },
    {
      "protocol": "tcp",
      "ports": "22",
      "sources": {
        "tags": [
          "gateway"
        ],
        "addresses": [
          "18.0.0.0/8"
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "protocol": "tcp",
      "ports": "8080",
      "destinations": {
        "addresses": [
          "0.0.0.0/0",
          "::/0"
        ]
      }
    }
  ],
  "droplet_ids": [
    8043964
  ],
  "tags": [
    "frontend"
  ]
}

resp = client.firewalls.update(firewall_id="3afda9", body=req)

Responses

200

The response will be a JSON object with a firewall key. This will be set to an object containing the standard firewall attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

firewall object optional

Show child properties

created_at string (date-time) optional read-only

Example: 2020-05-23T21:24:00Z

A time value given in ISO8601 combined date and time format that represents when the firewall was created.

droplet_ids array of integer optional Nullable

Example: [8043964]

An array containing the IDs of the Droplets assigned to the firewall.

Requires droplet:read scope.

id string optional read-only

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

name string optional

Example: firewall

A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

pending_changes array of object optional read-only

Example: [{"droplet_id":8043964,"removing":false,"status":"waiting"}]

Show child properties

droplet_id integer optional

Example: 8043964

removing boolean optional

Example: false

status string optional

Example: waiting

status string, one of: waiting, succeeded, failed optional read-only

Example: waiting

A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

tags object optional

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "firewall": {
    "created_at": "2020-05-23T21:24:00Z",
    "droplet_ids": [
      8043964
    ],
    "id": "bb4b2611-3d72-467b-8602-280330ecd65c",
    "inbound_rules": [
      {
        "ports": "80",
        "protocol": "tcp",
        "sources": {
          "load_balancer_uids": [
            "4de7ac8b-495b-4884-9a69-1050c6793cd6"
          ]
        }
      },
      {
        "ports": "22",
        "protocol": "tcp",
        "sources": {
          "addresses": [
            "18.0.0.0/8"
          ],
          "tags": [
            "gateway"
          ]
        }
      }
    ],
    "name": "frontend-firewall",
    "outbound_rules": [
      {
        "destinations": {
          "addresses": [
            "0.0.0.0/0",
            "::/0"
          ]
        },
        "ports": "80",
        "protocol": "tcp"
      }
    ],
    "pending_changes": [
      {
        "droplet_id": 8043964,
        "removing": false,
        "status": "waiting"
      }
    ],
    "status": "waiting",
    "tags": [
      "frontend"
    ]
  }
}

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Firewall

/v2/firewalls/{firewall_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a firewall send a DELETE request to /v2/firewalls/$FIREWALL_ID.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request: `/v2/firewalls/{firewall_id}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Firewalls.Delete(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c')
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.delete(id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.firewalls.delete(firewall_id= "as9di9d")

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Add Droplets to a Firewall

/v2/firewalls/{firewall_id}/droplets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To assign a Droplet to a firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

droplet_ids array of integer required

Example: [49696269]

An array containing the IDs of the Droplets to be assigned to the firewall.

Request: `/v2/firewalls/{firewall_id}/droplets`

Payload

Content type application/json

{
  "droplet_ids": [
    49696269
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"droplet_ids":[49696269]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Firewalls.AddDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269) 
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.add_droplets([49696269], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "droplet_ids": [
    49696269
  ]
}

resp = client.firewalls.assign_droplets(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Remove Droplets from a Firewall

/v2/firewalls/{firewall_id}/droplets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To remove a Droplet from a firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

droplet_ids array of integer required

Example: [49696269]

An array containing the IDs of the Droplets to be removed from the firewall.

Request: `/v2/firewalls/{firewall_id}/droplets`

Payload

Content type application/json

{
  "droplet_ids": [
    49696269
  ]
}

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"droplet_ids":[49696269]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Firewalls.RemoveDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.remove_droplets([49696269], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "droplet_ids": [
    49696269
  ]
}

resp = client.firewalls.delete_droplets(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Add Rules to a Firewall

/v2/firewalls/{firewall_id}/rules

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To add additional access rules to a firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/rules. The body of the request may include an inbound_rules and/or outbound_rules attribute containing an array of rules to be added.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

Request: `/v2/firewalls/{firewall_id}/rules`

Payload

Content type application/json

{
  "inbound_rules": [
    {
      "ports": "3306",
      "protocol": "tcp",
      "sources": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "destinations": {
        "droplet_ids": [
          49696269
        ]
      },
      "ports": "3306",
      "protocol": "tcp"
    }
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

ruleRequest := &godo.FirewallRulesRequest{
    InboundRules: []godo.InboundRule{
        {
            Protocol:      'tcp',
            PortRange:     '3306',
            Sources: &godo.Sources{
                DropletIDs: []int{49696269},
            },
        },
    },
    OutboundRules: []godo.OutboundRule{
        {
            Protocol:      'tcp',
            PortRange:     '3306',
            Destinations: &godo.Destinations{
                DropletIDs: []int{49696269},
            },
        },
    },
}

_, err := c.Firewalls.AddRules(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

inbound_rule = DropletKit::FirewallInboundRule.new(
  protocol: 'tcp',
  ports: '3306',
  sources: {
    droplet_ids: [49696269]
  }
)

outbound_rule = DropletKit::FirewallOutboundRule.new(
  protocol: 'tcp',
  ports: '3306',
  destinations: {
    droplet_ids: [49696269]
  }
)

client.firewalls.add_rules(inbound_rules: [inbound_rule], outbound_rules: [outbound_rule], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "inbound_rules": [
    {
      "protocol": "tcp",
      "ports": "3306",
      "sources": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "protocol": "tcp",
      "ports": "3306",
      "destinations": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ]
}

resp = client.firewalls.add_rules(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Remove Rules from a Firewall

/v2/firewalls/{firewall_id}/rules

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To remove access rules from a firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/rules. The body of the request may include an inbound_rules and/or outbound_rules attribute containing an array of rules to be removed.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

inbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

sources object required

outbound_rules array of object optional Nullable

Show child properties

ports string required

Example: 8000

protocol string, one of: tcp, udp, icmp required

Example: tcp

The type of traffic to be allowed. This may be one of tcp, udp, or icmp.

destinations object required

Request: `/v2/firewalls/{firewall_id}/rules`

Payload

Content type application/json

{
  "inbound_rules": [
    {
      "ports": "3306",
      "protocol": "tcp",
      "sources": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "destinations": {
        "droplet_ids": [
          49696269
        ]
      },
      "ports": "3306",
      "protocol": "tcp"
    }
  ]
}

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    ruleRequest := &godo.FirewallRulesRequest{
        InboundRules: []godo.InboundRule{
            {
                Protocol:      'tcp',
                PortRange:     '3306',
                Sources: &godo.Sources{
                    DropletIDs: []int{49696269},
                },
            },
        },
        OutboundRules: []godo.OutboundRule{
            {
                Protocol:      'tcp',
                PortRange:     '3306',
                Destinations: &godo.Destinations{
                    DropletIDs: []int{49696269},
                },
            },
        },
    }

    _, err := c.Firewalls.RemoveRules(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest)

}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

inbound_rule = DropletKit::FirewallInboundRule.new(
  protocol: 'tcp',
  ports: '3306',
  sources: {
    droplet_ids: [49696269]
  }
)

outbound_rule = DropletKit::FirewallOutboundRule.new(
  protocol: 'tcp',
  ports: '3306',
  destinations: {
    droplet_ids: [49696269]
  }
)

client.firewalls.remove_rules(inbound_rules: [inbound_rule], outbound_rules: [outbound_rule], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "inbound_rules": [
    {
      "protocol": "tcp",
      "ports": "3306",
      "sources": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ],
  "outbound_rules": [
    {
      "protocol": "tcp",
      "ports": "3306",
      "destinations": {
        "droplet_ids": [
          49696269
        ]
      }
    }
  ]
}

resp = client.firewalls.delete_rules(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Add Tags to a Firewall

/v2/firewalls/{firewall_id}/tags

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To assign a tag representing a group of Droplets to a firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/tags. In the body of the request, there should be a tags attribute containing a list of tag names.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

tags object required

Request: `/v2/firewalls/{firewall_id}/tags`

Payload

Content type application/json

{
  "tags": [
    "frontend"
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"tags":["frontend"]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Firewalls.AddTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend') 
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.add_tags(['frontend'], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "tags": [
    "frontend"
  ]
}

resp = client.firewalls.add_tags(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Remove Tags from a Firewall

/v2/firewalls/{firewall_id}/tags

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: firewall:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To remove a tag representing a group of Droplets from a firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/tags. In the body of the request, there should be a tags attribute containing a list of tag names.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

firewall_id string (uuid) required

Example: bb4b2611-3d72-467b-8602-280330ecd65c

A unique ID that can be used to identify and reference a firewall.

Request Body: `application/json`

tags object required

Request: `/v2/firewalls/{firewall_id}/tags`

Payload

Content type application/json

{
  "tags": [
    "frontend"
  ]
}

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"tags":["frontend"]}' \
  "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.Firewalls.RemoveTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend')
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.firewalls.remove_tags(['frontend'], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "tags": [
    "frontend"
  ]
}

resp = client.firewalls.delete_tags(firewall_id="39fa4gz", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

There was an error parsing the request body.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

400

{
  "id": "bad_request",
  "message": "error parsing request body",
  "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

Cloud Firewalls API Reference

Endpoints

GET List All Firewalls

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/firewalls

Responses

Response

POST Create a New Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/firewalls

Responses

Response

GET Retrieve an Existing Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/firewalls/{firewall_id}

Responses

Response

PUT Update a Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/firewalls/{firewall_id}

Responses

Response

DELETE Delete a Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/firewalls/{firewall_id}

Responses

Response

POST Add Droplets to a Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/firewalls/{firewall_id}/droplets

Responses

Response

DELETE Remove Droplets from a Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/firewalls/{firewall_id}/droplets

Responses

Response

POST Add Rules to a Firewall

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/firewalls/{firewall_id}/rules

Responses

Response

DELETE Remove Rules from a Firewall

OAuth Authentication

Request: `/v2/firewalls`

Request Body: `application/json`

Request: `/v2/firewalls`

Request: `/v2/firewalls/{firewall_id}`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}`

Request: `/v2/firewalls/{firewall_id}`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/droplets`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/droplets`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/rules`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/rules`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/tags`

Request Body: `application/json`

Request: `/v2/firewalls/{firewall_id}/tags`