public API documentation for Secrets Manager

specification/DigitalOcean-public.v2.yaml

@@ -534,7 +534,7 @@ tags:
 
   - name: Security
     description: |-
-      Security CSPM endpoints for scans, scan findings, and settings.
+      Security endpoints for CSPM scans, scan findings, settings, and Secrets Manager.
 
   - name: Sizes
     description: |-
@@ -2294,6 +2294,31 @@ paths:
     delete:
       $ref: "resources/security/security_suppression_delete.yml"
 
+  /v2/security/secrets:
+    get:
+      $ref: "resources/security/security_secrets_list.yml"
+
+    post:
+      $ref: "resources/security/security_secret_create.yml"
+
+  /v2/security/secrets/{secret}:
+    get:
+      $ref: "resources/security/security_secret_get.yml"
+
+    put:
+      $ref: "resources/security/security_secret_update.yml"
+
+    delete:
+      $ref: "resources/security/security_secret_delete.yml"
+
+  /v2/security/secrets/{secret}/versions:
+    get:
+      $ref: "resources/security/security_secret_list_versions.yml"
+
+  /v2/security/secrets/{secret}/restore:
+    post:
+      $ref: "resources/security/security_secret_restore.yml"
+
   /v2/sizes:
     get:
       $ref: "resources/sizes/sizes_list.yml"

specification/resources/security/examples/curl/security_secret_create.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secret_delete.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secret_get.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secret_list_versions.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secret_restore.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secret_update.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/examples/curl/security_secrets_list.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  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"

specification/resources/security/models/secret.yml

@@ -0,0 +1,140 @@
+secret:
+  type: object
+  properties:
+    secret:
+      title: secret
+      type: string
+      example: my-database-password
+      description: The name of the secret.
+
+    region:
+      title: region
+      type: string
+      example: nyc3
+      description: The region where the secret is stored.
+
+    version:
+      title: version
+      type: integer
+      format: int32
+      example: 1
+      description: The current version of the secret.
+
+    values:
+      title: values
+      type: object
+      additionalProperties:
+        type: string
+      example:
+        password: s3cr3t
+      description: Key-value pairs stored in the secret.
+
+    created_at:
+      title: created_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When the secret was created.
+
+    updated_at:
+      title: updated_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When the secret was last updated.
+
+    delete_requested_at:
+      title: delete_requested_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When deletion was requested for the secret.
+
+secret_list_item:
+  type: object
+  properties:
+    secret:
+      title: secret
+      type: string
+      example: my-database-password
+      description: The name of the secret.
+
+    region:
+      title: region
+      type: string
+      example: nyc3
+      description: The region where the secret is stored.
+
+    version:
+      title: version
+      type: integer
+      format: int32
+      example: 1
+      description: The current version of the secret.
+
+    created_at:
+      title: created_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When the secret was created.
+
+    updated_at:
+      title: updated_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When the secret was last updated.
+
+    delete_requested_at:
+      title: delete_requested_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When deletion was requested for the secret.
+
+secret_version:
+  type: object
+  properties:
+    version:
+      title: version
+      type: integer
+      format: int32
+      example: 1
+      description: The version number.
+
+    created_at:
+      title: created_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When this version was created.
+
+    updated_at:
+      title: updated_at
+      type: string
+      format: date-time
+      example: "2025-12-04T00:00:00Z"
+      description: When this version was last updated.
+
+create_secret_response:
+  type: object
+  properties:
+    name:
+      title: name
+      type: string
+      example: my-database-password
+      description: The name of the secret.
+
+    region:
+      title: region
+      type: string
+      example: nyc3
+      description: The region where the secret is stored.
+
+    version:
+      title: version
+      type: integer
+      format: int32
+      example: 1
+      description: The version of the secret after the operation.

specification/resources/security/parameters.yml

@@ -41,3 +41,12 @@ suppression_uuid:
     type: string
     format: uuid
   example: 5b3b2b2d-5c9c-4a61-9e2f-4d8f80f30a12
+
+secret:
+  in: path
+  name: secret
+  description: The name of the secret.
+  required: true
+  schema:
+    type: string
+  example: my-database-password

specification/resources/security/responses/create_secret.yml

@@ -0,0 +1,14 @@
+description: The response will be a JSON object containing the secret name, region, and version.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      $ref: '../models/secret.yml#/create_secret_response'

specification/resources/security/responses/secret.yml

@@ -0,0 +1,14 @@
+description: The response will be a JSON object containing the secret and its values.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      $ref: '../models/secret.yml#/secret'

specification/resources/security/responses/secret_versions.yml

@@ -0,0 +1,19 @@
+description: The response will be a JSON object with a key called `versions`.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        versions:
+          type: array
+          items:
+            $ref: '../models/secret.yml#/secret_version'

specification/resources/security/responses/secrets.yml

@@ -0,0 +1,67 @@
+description: 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.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        secrets:
+          type: array
+          items:
+            $ref: '../models/secret.yml#/secret_list_item'
+        meta:
+          type: object
+          properties:
+            page:
+              type: integer
+              format: int32
+              example: 1
+              description: The current page number.
+            pages:
+              type: integer
+              format: int32
+              example: 5
+              description: The total number of pages.
+            total:
+              type: integer
+              format: int32
+              example: 42
+              description: The total number of secrets across all regions.
+        links:
+          type: object
+          properties:
+            pages:
+              type: object
+              properties:
+                first:
+                  type: string
+                  example: "https://api.digitalocean.com/v2/security/secrets?page=1&per_page=20"
+                  description: URL for the first page of results.
+                prev:
+                  type: string
+                  example: "https://api.digitalocean.com/v2/security/secrets?page=1&per_page=20"
+                  description: URL for the previous page of results.
+                next:
+                  type: string
+                  example: "https://api.digitalocean.com/v2/security/secrets?page=3&per_page=20"
+                  description: URL for the next page of results.
+                last:
+                  type: string
+                  example: "https://api.digitalocean.com/v2/security/secrets?page=5&per_page=20"
+                  description: URL for the last page of results.
+        unavailable_regions:
+          type: array
+          items:
+            type: string
+          example:
+            - sfo3
+          description: Regions that could not be queried while building the list response.