Give Feedback

Security

Generated on 2 Jul 2026

Copy page as Markdown View page as Markdown

Security endpoints for CSPM scans, scan findings, settings, and Secrets Manager.

Base URL https://api.digitalocean.com

Endpoints

GET List Scans POST Create Scan GET Get Scan GET Get Latest Scan POST Create Scan Rule GET List Finding Affected Resources GET List Settings PUT Update Plan POST Create Suppression DELETE Delete Suppression GET List Secrets POST Create Secret GET Get Secret PUT Update Secret DELETE Delete Secret GET List Secret Versions POST Restore Secret

GET List Scans

/v2/security/scans

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 CSPM scans, send a GET request to /v2/security/scans.

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/security/scans`

cURL

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

Responses

200

The response will be a JSON object with a key called scans. This will be set to an array of objects, each of which will contain the standard attributes associated with a scan.

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

scans array of object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When scan was created.

findings array of object optional

Show child properties

affected_resources_count integer optional

Example: 12

The number of affected resources for the finding.

business_impact string optional

A description of the business impact of the finding.

details string optional

A description of the risk associated with the finding.

found_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the finding was discovered.

mitigation_steps array of object optional

The mitigation steps to resolve the finding.

Show child properties

description string optional

Example: Turn on automated backups for this Droplet.

step integer optional

Example: 1

title string optional

Example: Enable backups

name string optional

Example: All Firewall Ports Exposed to a Source

The name of the rule that triggered the finding.

rule_uuid string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the rule that triggered the finding.

severity string, one of: CRITICAL, HIGH, MEDIUM, LOW optional

Example: CRITICAL

The severity of the finding.

technical_details string optional

A description of the technical details related to the finding.

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the scan.

status string, one of: IN_PROGRESS, COMPLETED, FAILED, CSPM_NOT_ENABLED, SCAN_NOT_RUN optional

Example: COMPLETED

The status of the scan.

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.

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

{
  "links": {
    "pages": {
      "pages": {
        "first": "https://api.digitalocean.com/v2/account/keys?page=1",
        "prev": "https://api.digitalocean.com/v2/account/keys?page=2"
      }
    }
  },
  "meta": {
    "total": 1
  },
  "scans": [
    {
      "created_at": "2025-12-04T00:00:00Z",
      "findings": [],
      "id": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "status": "COMPLETED"
    }
  ]
}

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 Create Scan

/v2/security/scans

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 CSPM scan, send a POST request to /v2/security/scans.

Request: `/v2/security/scans`

cURL

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

Responses

201

The response will be a JSON object with a key called scan.

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

scan object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When scan was created.

findings array of object optional

Show child properties

affected_resources_count integer optional

Example: 12

The number of affected resources for the finding.

business_impact string optional

A description of the business impact of the finding.

details string optional

A description of the risk associated with the finding.

found_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the finding was discovered.

mitigation_steps array of object optional

The mitigation steps to resolve the finding.

Show child properties

description string optional

Example: Turn on automated backups for this Droplet.

step integer optional

Example: 1

title string optional

Example: Enable backups

name string optional

Example: All Firewall Ports Exposed to a Source

The name of the rule that triggered the finding.

rule_uuid string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the rule that triggered the finding.

severity string, one of: CRITICAL, HIGH, MEDIUM, LOW optional

Example: CRITICAL

The severity of the finding.

technical_details string optional

A description of the technical details related to the finding.

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the scan.

status string, one of: IN_PROGRESS, COMPLETED, FAILED, CSPM_NOT_ENABLED, SCAN_NOT_RUN optional

Example: COMPLETED

The status of the scan.

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

201

{
  "scan": {
    "created_at": "2025-12-04T00:00:00Z",
    "findings": [],
    "id": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
    "status": "COMPLETED"
  }
}

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

GET Get Scan

/v2/security/scans/{scan_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 get a CSPM scan by ID, send a GET request to /v2/security/scans/{scan_id}.

Path Parameters

scan_id string (uuid) required

Example: 497dcba3-ecbf-4587-a2dd-5eb0665e6880

The scan UUID.

Query Parameters

severity string, one of: LOW, MEDIUM, HIGH, CRITICAL optional

Example: CRITICAL

The finding severity level to include.

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

type string optional

Example: CSPM

The finding type to include.

Request: `/v2/security/scans/{scan_id}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/scans/497dcba3-ecbf-4587-a2dd-5eb0665e6880"

Responses

200

The response will be a JSON object with a key called scan.

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

scan object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When scan was created.

findings array of object optional

Show child properties

affected_resources_count integer optional

Example: 12

The number of affected resources for the finding.

business_impact string optional

A description of the business impact of the finding.

details string optional

A description of the risk associated with the finding.

found_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the finding was discovered.

mitigation_steps array of object optional

The mitigation steps to resolve the finding.

Show child properties

description string optional

Example: Turn on automated backups for this Droplet.

step integer optional

Example: 1

title string optional

Example: Enable backups

name string optional

Example: All Firewall Ports Exposed to a Source

The name of the rule that triggered the finding.

rule_uuid string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the rule that triggered the finding.

severity string, one of: CRITICAL, HIGH, MEDIUM, LOW optional

Example: CRITICAL

The severity of the finding.

technical_details string optional

A description of the technical details related to the finding.

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the scan.

status string, one of: IN_PROGRESS, COMPLETED, FAILED, CSPM_NOT_ENABLED, SCAN_NOT_RUN optional

Example: COMPLETED

The status of the scan.

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

{
  "scan": {
    "created_at": "2025-12-04T00:00:00Z",
    "findings": [],
    "id": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
    "status": "COMPLETED"
  }
}

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

GET Get Latest Scan

/v2/security/scans/latest

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 get the latest CSPM scan, send a GET request to /v2/security/scans/latest.

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

severity string, one of: LOW, MEDIUM, HIGH, CRITICAL optional

Example: CRITICAL

The finding severity level to include.

type string optional

Example: CSPM

The finding type to include.

Request: `/v2/security/scans/latest`

cURL

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

Responses

200

The response will be a JSON object with a key called scan.

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

scan object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When scan was created.

findings array of object optional

Show child properties

affected_resources_count integer optional

Example: 12

The number of affected resources for the finding.

business_impact string optional

A description of the business impact of the finding.

details string optional

A description of the risk associated with the finding.

found_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the finding was discovered.

mitigation_steps array of object optional

The mitigation steps to resolve the finding.

Show child properties

description string optional

Example: Turn on automated backups for this Droplet.

step integer optional

Example: 1

title string optional

Example: Enable backups

name string optional

Example: All Firewall Ports Exposed to a Source

The name of the rule that triggered the finding.

rule_uuid string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the rule that triggered the finding.

severity string, one of: CRITICAL, HIGH, MEDIUM, LOW optional

Example: CRITICAL

The severity of the finding.

technical_details string optional

A description of the technical details related to the finding.

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

The unique identifier for the scan.

status string, one of: IN_PROGRESS, COMPLETED, FAILED, CSPM_NOT_ENABLED, SCAN_NOT_RUN optional

Example: COMPLETED

The status of the scan.

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

{
  "scan": {
    "created_at": "2025-12-04T00:00:00Z",
    "findings": [],
    "id": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
    "status": "COMPLETED"
  }
}

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 Create Scan Rule

/v2/security/scans/rules

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 mark a scan finding as a false positive, send a POST request to /v2/security/scans/rules to create a new scan rule.

Request Body: `application/json`

resource string optional

Example: do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d

The URN of a resource to exclude from future scans.

Request: `/v2/security/scans/rules`

Payload

Content type application/json

{
  "resource": "do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"resource": "do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"}' \
  "https://api.digitalocean.com/v2/security/scans/rules"

Responses

201

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

GET List Finding Affected Resources

/v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 get affected resources for a scan finding, send a GET request to /v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources.

Path Parameters

scan_id string (uuid) required

Example: 497dcba3-ecbf-4587-a2dd-5eb0665e6880

The scan UUID.

finding_uuid string (uuid) required

Example: 50e14f43-dd4e-412f-864d-78943ea28d91

The finding UUID.

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/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/scans/497dcba3-ecbf-4587-a2dd-5eb0665e6880/findings/50e14f43-dd4e-412f-864d-78943ea28d91/affected_resources"

Responses

200

The response will be a JSON object with a key called affected_resources.

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

affected_resources array of object optional

Show child properties

name string optional

Example: Test Droplet

The name of the affected resource.

type string optional

Example: Droplet

The type of the affected resource.

urn string optional

Example: do:droplet:760e09ef-dc84-11e8-981e-3cfdfeaae000

The URN for the affected resource.

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

{
  "affected_resources": [
    {
      "name": "Test Droplet",
      "type": "Droplet",
      "urn": "do:droplet:760e09ef-dc84-11e8-981e-3cfdfeaae000"
    }
  ]
}

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

GET List Settings

/v2/security/settings

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 list CSPM scan settings, send a GET request to /v2/security/settings.

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/security/settings`

cURL

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

Responses

200

The response will be a JSON object with scan settings.

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

plan_downgrades object optional

Show child properties

(additional properties) object optional

Additional properties are allowed.

settings object optional

Show child properties

suppressions object optional

Show child properties

links object optional

Show child properties

pages object optional

Additional nested properties not shown. Refer to the full API spec for details.

meta object optional

Show child properties

page integer optional

Example: 1

pages integer optional

Example: 3

total integer optional

Example: 25

resources array of object optional

Show child properties

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

Unique identifier for the suppressed resource.

resource_id string optional

Example: 123

Unique identifier for the resource suppressed.

resource_type string optional

Example: Droplet

Resource type for the resource suppressed.

rule_name string optional

Example: Droplet Backups Not Enabled

Human-readable rule name for the suppressed rule.

rule_uuid string optional

Example: 460e09ef-dc84-11e8-981e-3cfdfeaae000

Unique identifier for the suppressed rule.

tier_coverage object optional

Show child properties

(additional properties) object optional

Additional properties are allowed.

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

{
  "settings": {
    "suppressions": {
      "resources": []
    }
  }
}

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 Plan

/v2/security/settings/plan

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 CSPM plan coverage, send a PUT request to /v2/security/settings/plan.

Request Body: `application/json`

tier_coverage object optional

Example: {"basic":{"resources":["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"],"tags":["production"]}}

Scan coverage for each available plan tier.

Show child properties

(additional properties) object optional

Additional properties are allowed.

Request: `/v2/security/settings/plan`

Payload

Content type application/json

{
  "tier_coverage": {
    "basic": {
      "resources": [
        "do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"
      ],
      "tags": [
        "production"
      ]
    }
  }
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"tier_coverage":{"basic":{"resources":["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"],"tags":["production"]}}}' \
  "https://api.digitalocean.com/v2/security/settings/plan"

Responses

200

The response will be a JSON object with updated tier coverage.

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

tier_coverage object optional

Show child properties

(additional properties) object optional

Additional properties are allowed.

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 Create Suppression

/v2/security/settings/suppressions

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 suppress scan findings, send a POST request to /v2/security/settings/suppressions.

Request Body: `application/json`

resources array of string optional

Example: ["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"]

The URNs of resources to suppress for the rule.

rule_uuid string optional

The rule UUID to suppress for the listed resources.

Request: `/v2/security/settings/suppressions`

Payload

Content type application/json

{
  "resources": [
    "do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"
  ],
  "rule_uuid": "string"
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"rule_uuid":"497dcba3-ecbf-4587-a2dd-5eb0665e6880","resources":["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"]}' \
  "https://api.digitalocean.com/v2/security/settings/suppressions"

Responses

201

The response will be a JSON object containing suppressed resources.

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

links object optional

Show child properties

pages object optional

Show child properties

first string optional

Example: https://api.digitalocean.com/v2/security/settings/suppressions?page=1

last string optional

Example: https://api.digitalocean.com/v2/security/settings/suppressions?page=3

next string optional

Example: https://api.digitalocean.com/v2/security/settings/suppressions?page=2

prev string optional

Example: https://api.digitalocean.com/v2/security/settings/suppressions?page=1

meta object optional

Show child properties

page integer optional

Example: 1

pages integer optional

Example: 3

total integer optional

Example: 25

resources array of object optional

Show child properties

id string optional

Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

Unique identifier for the suppressed resource.

resource_id string optional

Example: 123

Unique identifier for the resource suppressed.

resource_type string optional

Example: Droplet

Resource type for the resource suppressed.

rule_name string optional

Example: Droplet Backups Not Enabled

Human-readable rule name for the suppressed rule.

rule_uuid string optional

Example: 460e09ef-dc84-11e8-981e-3cfdfeaae000

Unique identifier for the suppressed rule.

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

201

{
  "links": {
    "pages": {
      "first": "https://api.digitalocean.com/v2/security/settings/suppressions?page=1",
      "last": "https://api.digitalocean.com/v2/security/settings/suppressions?page=3",
      "next": "https://api.digitalocean.com/v2/security/settings/suppressions?page=2",
      "prev": "https://api.digitalocean.com/v2/security/settings/suppressions?page=1"
    }
  },
  "meta": {
    "page": 1,
    "pages": 3,
    "total": 25
  },
  "resources": [
    {
      "id": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "resource_id": "123",
      "resource_type": "Droplet",
      "rule_name": "Droplet Backups Not Enabled",
      "rule_uuid": "460e09ef-dc84-11e8-981e-3cfdfeaae000"
    }
  ]
}

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 Suppression

/v2/security/settings/suppressions/{suppression_uuid}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 remove a suppression, send a DELETE request to /v2/security/settings/suppressions/{suppression_uuid}.

Path Parameters

suppression_uuid string (uuid) required

Example: 5b3b2b2d-5c9c-4a61-9e2f-4d8f80f30a12

The suppression UUID to remove.

Request: `/v2/security/settings/suppressions/{suppression_uuid}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/settings/suppressions/5b3b2b2d-5c9c-4a61-9e2f-4d8f80f30a12"

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

GET List Secrets

/v2/security/secrets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 list secrets across all configured regions, send a GET request to /v2/security/secrets.

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/security/secrets`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/secrets?page=1&per_page=20"

Responses

200

The response will be a JSON object with a key called secrets. This will be set to an array of objects, each of which will contain the standard attributes associated with a secret.

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

links object optional

Show child properties

pages object optional

Show child properties

first string optional

Example: https://api.digitalocean.com/v2/security/secrets?page=1&per_page=20

URL for the first page of results.

last string optional

Example: https://api.digitalocean.com/v2/security/secrets?page=5&per_page=20

URL for the last page of results.

next string optional

Example: https://api.digitalocean.com/v2/security/secrets?page=3&per_page=20

URL for the next page of results.

prev string optional

Example: https://api.digitalocean.com/v2/security/secrets?page=1&per_page=20

URL for the previous page of results.

meta object optional

Show child properties

page integer (int32) optional

Example: 1

The current page number.

pages integer (int32) optional

Example: 5

The total number of pages.

total integer (int32) optional

Example: 42

The total number of secrets across all regions.

secrets array of object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was created.

delete_requested_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When deletion was requested for the secret.

region string optional

Example: nyc3

The region where the secret is stored.

secret string optional

Example: my-database-password

The name of the secret.

updated_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was last updated.

version integer (int32) optional

Example: 1

The current version of the secret.

unavailable_regions array of string optional

Example: ["sfo3"]

Regions that could not be queried while building the list response.

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

{
  "links": {
    "pages": {
      "first": "https://api.digitalocean.com/v2/security/secrets?page=1\u0026per_page=20",
      "last": "https://api.digitalocean.com/v2/security/secrets?page=5\u0026per_page=20",
      "next": "https://api.digitalocean.com/v2/security/secrets?page=3\u0026per_page=20",
      "prev": "https://api.digitalocean.com/v2/security/secrets?page=1\u0026per_page=20"
    }
  },
  "meta": {
    "page": 1,
    "pages": 5,
    "total": 42
  },
  "secrets": [
    {
      "created_at": "2025-12-04T00:00:00Z",
      "delete_requested_at": "2025-12-04T00:00:00Z",
      "region": "nyc3",
      "secret": "my-database-password",
      "updated_at": "2025-12-04T00:00:00Z",
      "version": 1
    }
  ],
  "unavailable_regions": [
    "sfo3"
  ]
}

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 Secret

/v2/security/secrets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 secret, send a POST request to /v2/security/secrets.

Request Body: `application/json`

name string required

Example: my-database-password

The name of the secret to create.

region string required

Example: nyc3

The region where the secret will be stored.

values object required

Example: {"password":"s3cr3t"}

Key-value pairs to store in the secret.

Request: `/v2/security/secrets`

Payload

Content type application/json

{
  "name": "my-database-password",
  "region": "nyc3",
  "values": {
    "password": "s3cr3t"
  }
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"my-database-password","region":"nyc3","values":{"password":"s3cr3t"}}' \
  "https://api.digitalocean.com/v2/security/secrets"

Responses

200

The response will be a JSON object containing the secret name, region, and version.

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

name string optional

Example: my-database-password

The name of the secret.

region string optional

Example: nyc3

The region where the secret is stored.

version integer (int32) optional

Example: 1

The version of the secret after the operation.

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

200

{
  "name": "my-database-password",
  "region": "nyc3",
  "version": 1
}

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 Get Secret

/v2/security/secrets/{secret}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 retrieve a secret and its values, send a GET request to /v2/security/secrets/{secret}.

Path Parameters

secret string required

Example: my-database-password

The name of the secret.

Query Parameters

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource is available.

Request: `/v2/security/secrets/{secret}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/secrets/my-database-password?region=nyc3"

Responses

200

The response will be a JSON object containing the secret and its values.

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

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was created.

delete_requested_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When deletion was requested for the secret.

region string optional

Example: nyc3

The region where the secret is stored.

secret string optional

Example: my-database-password

The name of the secret.

updated_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was last updated.

values object optional

Example: {"password":"s3cr3t"}

Key-value pairs stored in the secret.

version integer (int32) optional

Example: 1

The current version of the secret.

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

{
  "created_at": "2025-12-04T00:00:00Z",
  "delete_requested_at": "2025-12-04T00:00:00Z",
  "region": "nyc3",
  "secret": "my-database-password",
  "updated_at": "2025-12-04T00:00:00Z",
  "values": {
    "password": "s3cr3t"
  },
  "version": 1
}

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 Secret

/v2/security/secrets/{secret}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 a secret, send a PUT request to /v2/security/secrets/{secret}.

Path Parameters

secret string required

Example: my-database-password

The name of the secret.

Request Body: `application/json`

region string required

Example: nyc3

The region where the secret is stored.

values object required

Example: {"password":"n3w-s3cr3t"}

Updated key-value pairs for the secret.

version integer (int32) required

Example: 1

The current version of the secret to update.

Request: `/v2/security/secrets/{secret}`

Payload

Content type application/json

{
  "region": "nyc3",
  "values": {
    "password": "n3w-s3cr3t"
  },
  "version": 1
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"region":"nyc3","version":1,"values":{"password":"n3w-s3cr3t"}}' \
  "https://api.digitalocean.com/v2/security/secrets/my-database-password"

Responses

200

The response will be a JSON object containing the secret name, region, and version.

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

name string optional

Example: my-database-password

The name of the secret.

region string optional

Example: nyc3

The region where the secret is stored.

version integer (int32) optional

Example: 1

The version of the secret after the operation.

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

{
  "name": "my-database-password",
  "region": "nyc3",
  "version": 1
}

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 Secret

/v2/security/secrets/{secret}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 request deletion of a secret, send a DELETE request to /v2/security/secrets/{secret}.

Path Parameters

secret string required

Example: my-database-password

The name of the secret.

Query Parameters

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource is available.

Request: `/v2/security/secrets/{secret}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/secrets/my-database-password?region=nyc3"

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

GET List Secret Versions

/v2/security/secrets/{secret}/versions

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 list all versions of a secret, send a GET request to /v2/security/secrets/{secret}/versions.

Path Parameters

secret string required

Example: my-database-password

The name of the secret.

Query Parameters

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource is available.

Request: `/v2/security/secrets/{secret}/versions`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/secrets/my-database-password/versions?region=nyc3"

Responses

200

The response will be a JSON object with a key called versions.

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

versions array of object optional

Show child properties

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When this version was created.

updated_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When this version was last updated.

version integer (int32) optional

Example: 1

The version number.

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

{
  "versions": [
    {
      "created_at": "2025-12-04T00:00:00Z",
      "updated_at": "2025-12-04T00:00:00Z",
      "version": 1
    }
  ]
}

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 Restore Secret

/v2/security/secrets/{secret}/restore

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: security: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 restore a deleted secret, send a POST request to /v2/security/secrets/{secret}/restore.

Path Parameters

secret string required

Example: my-database-password

The name of the secret.

Query Parameters

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource is available.

Request: `/v2/security/secrets/{secret}/restore`

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/security/secrets/my-database-password/restore?region=nyc3"

Responses

200

The response will be a JSON object containing the secret and its values.

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

created_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was created.

delete_requested_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When deletion was requested for the secret.

region string optional

Example: nyc3

The region where the secret is stored.

secret string optional

Example: my-database-password

The name of the secret.

updated_at string (date-time) optional

Example: 2025-12-04T00:00:00Z

When the secret was last updated.

values object optional

Example: {"password":"s3cr3t"}

Key-value pairs stored in the secret.

version integer (int32) optional

Example: 1

The current version of the secret.

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

{
  "created_at": "2025-12-04T00:00:00Z",
  "delete_requested_at": "2025-12-04T00:00:00Z",
  "region": "nyc3",
  "secret": "my-database-password",
  "updated_at": "2025-12-04T00:00:00Z",
  "values": {
    "password": "s3cr3t"
  },
  "version": 1
}

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

Security

Endpoints

GET List Scans

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/security/scans

Responses

Response

POST Create Scan

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request: /v2/security/scans

Responses

Response

GET Get Scan

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Query Parameters

Request: /v2/security/scans/{scan_id}

Responses

Response

GET Get Latest Scan

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/security/scans/latest

Responses

Response

POST Create Scan Rule

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/security/scans/rules

Responses

Response

GET List Finding Affected Resources

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Query Parameters

Request: /v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources

Responses

Response

GET List Settings

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/security/settings

Responses

Response

PUT Update Plan

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/security/settings/plan

Responses

Response

POST Create Suppression

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request: `/v2/security/scans`

Request: `/v2/security/scans`

Request: `/v2/security/scans/{scan_id}`

Request: `/v2/security/scans/latest`

Request Body: `application/json`

Request: `/v2/security/scans/rules`

Request: `/v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources`

Request: `/v2/security/settings`

Request Body: `application/json`

Request: `/v2/security/settings/plan`

Request Body: `application/json`

Request: `/v2/security/settings/suppressions`

Request: `/v2/security/settings/suppressions/{suppression_uuid}`

Request: `/v2/security/secrets`

Request Body: `application/json`

Request: `/v2/security/secrets`

Request: `/v2/security/secrets/{secret}`

Request Body: `application/json`

Request: `/v2/security/secrets/{secret}`

Request: `/v2/security/secrets/{secret}`

Request: `/v2/security/secrets/{secret}/versions`