Updating openapi docs for scopes

specification/resources/apps/models/apps_create_app_request.yml

@@ -5,7 +5,8 @@ properties:
     type: string
     description: |
       The ID of the project the app should be assigned to. If omitted, it will be assigned to your default project.
-      <br><br>Requires `project:assign_resource` and `project:update` scopes.
+      <br><br>Requires `project:update` scope. The `project:assign_resource` scope applies to the Projects API
+      resource-assignment endpoints, such as `POST /v2/projects/{project_id}/resources`, and is not sufficient for this check.
 required:
 - spec
 type: object

specification/resources/databases/databases_create_cluster.yml

@@ -41,6 +41,12 @@ description: >-
   documentation for the feature differences vs. Standard Edition and current preview limitations.
 
 
+  To enable storage autoscaling when the cluster is created, include a `storage_autoscale`
+  object with `enabled`, `threshold_percent`, and `increment_gib`. Storage autoscaling can
+  also be configured after the cluster is created by sending a PUT request to
+  `/v2/databases/$DATABASE_ID/autoscale`.
+
+
   Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z.
   Backups are also not supported for Caching or Valkey clusters.
 
@@ -71,6 +77,20 @@ requestBody:
             tags:
               - production
 
+        Create a New Database Cluster with storage autoscaling:
+          value:
+            name: backend
+            engine: pg
+            version: "14"
+            region: nyc3
+            size: db-s-2vcpu-4gb
+            num_nodes: 2
+            storage_size_mib: 61440
+            storage_autoscale:
+              enabled: true
+              threshold_percent: 80
+              increment_gib: 10
+
         Create a New Database Cluster with trusted sources:
           value:
             name: backend

specification/resources/databases/databases_get_ca.yml

@@ -9,6 +9,10 @@ description: |
   The response will be a JSON object with a `ca` key. This will be set to an object
   containing the base64 encoding of the public key certificate.
 
+  Retrieving the certificate content requires both the `database:read` and
+  `database:view_credentials` scopes. A token with only `database:read` still
+  receives a `200` response, but the `certificate` field is empty.
+
 tags:
   - Databases
 
@@ -42,4 +46,5 @@ x-codeSamples:
 security:
   - bearer_auth:
     - 'database:read'
+    - 'database:view_credentials'
 

specification/resources/databases/models/ca.yml

@@ -4,7 +4,10 @@ properties:
   certificate:
     type: string
     example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVRVENDQXFtZ0F3SUJBZ0lVRUZZWTdBWFZQS0Raam9jb1lpMk00Y0dvcU0wd0RRWUpLb1pJaHZjTkFRRU0KQlFBd09qRTRNRFlHQTFVRUF3d3ZOek0zT1RaaE1XRXRaamhrTUMwME9HSmpMV0V4Wm1NdFpqbGhNVFZsWXprdwpORGhsSUZCeWIycGxZM1FnUTBFd0hoY05NakF3TnpFM01UVTFNREEyV2hjTk16QXdOekUxTVRVMU1EQTJXakE2Ck1UZ3dOZ1lEVlFRRERDODNNemM1Tm1FeFlTMW1PR1F3TFRRNFltTXRZVEZtWXkxbU9XRXhOV1ZqT1RBME9HVWcKVUhKdmFtVmpkQ0JEUVRDQ0FhSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnR1BBRENDQVlvQ2dnR0JBTVdScXhycwpMZnpNdHZyUmxKVEw4MldYMVBLZkhKbitvYjNYcmVBY3FZd1dBUUp2Q3IycmhxSXZieVZzMGlaU0NzOHI4c3RGClljQ0R1bkxJNmUwTy9laERZYTBIT2RrMkFFRzE1ckVOVmNha2NSczcyQWlHVHNrdkNXS2VkUjFTUWswVWt0WCsKQUg4S1ExS3F5bzNtZ2Y2cVV1WUpzc3JNTXFselk3YTN1RVpEb2ZqTjN5Q3MvM21pTVJKcVcyNm1JV0IrUUlEbAo5YzdLRVF5MTZvdCtjeHVnd0lLMm9oZHMzaFY1bjBKMFVBM0I3QWRBdXY5aUl5L3JHaHlTNm5CNTdaWm9JZnAyCnFybXdOY0UrVjlIdXhQSGtRVjFOQjUwOFFudWZ4Z0E5VCtqU2VrdGVUbWFORkxqNjFXL3BtcndrTytOaWFXUTIKaGgzVXBKOEozY1BoNkErbHRnUmpSV2NEb2lsYVNwRVVpU09WemNNYVFvalZKYVJlNk9NbnZYc29NaSs3ZzdneApWcittQ0lUcGcvck9DaXpBWWQ2UFAxLzdYTjk1ZXNmU2tBQnM5c3hJakpjTUFqbDBYTEFzRmtGZVdyeHNIajlVCmJnaDNWYXdtcnpUeXhZT0RQcXV1cS9JcGlwc0RRT3Fpb2ZsUStkWEJJL3NUT0NNbVp6K0pNcG5HYXdJREFRQUIKb3o4d1BUQWRCZ05WSFE0RUZnUVVSekdDRlE3WEtUdHRDN3JzNS8ydFlQcExTZGN3RHdZRFZSMFRCQWd3QmdFQgovd0lCQURBTEJnTlZIUThFQkFNQ0FRWXdEUVlKS29aSWh2Y05BUUVNQlFBRGdnR0JBSWFKQ0dSVVNxUExtcmcvCmk3MW10b0NHUDdzeG1BVXVCek1oOEdrU25uaVdaZnZGMTRwSUtqTlkwbzVkWmpHKzZqK1VjalZtK0RIdGE1RjYKOWJPeEk5S0NFeEI1blBjRXpMWjNZYitNOTcrellxbm9zUm85S21DVFJBb2JrNTZ0WU1FS1h1aVJja2tkMm1yUQo4cGw2N2xxdThjM1V4c0dHZEZVT01wMkk3ZTNpdUdWVm5UR0ZWM3JQZUdaQ0J3WGVyUUQyY0F4UjkzS3BnWVZ2ClhUUzk5dnpSbm1HOHhhUm9EVy9FbEdXZ2xWd0Q5a1JrbXhUUkdoYTdDWVZCcjFQVWY2dVVFVjhmVFIxc1hFZnIKLytMR1JoSVVsSUhWT3l2Yzk3YnZYQURPbWF1MWZDVE5lWGtRdTNyZnZFSlBmaFlLeVIwT0V3eWVvdlhRNzl0LwpTV2ZGTjBreU1Pc1UrNVNIdHJKSEh1eWNWcU0yQlVVK083VjM1UnNwOU9MZGRZMFFVbTZldFpEVEhhSUhYYzRRCnl1Rm1OL1NhSFZtNE0wL3BTVlJQdVd6TmpxMnZyRllvSDRtbGhIZk95TUNJMjc2elE2aWhGNkdDSHlkOUJqajcKUm1UWGEyNHM3NWhmSi9YTDV2bnJSdEtpVHJlVHF6V21EOVhnUmNMQ0gyS1hJaVRtSWc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
-    description: base64 encoding of the certificate used to secure database connections
+    description: >-
+      A base64 encoding of the certificate used to secure database connections.
+      Requires the `database:view_credentials` scope. A token with only `database:read`
+      receives an empty string.
     readOnly: true
 
 required:

specification/resources/databases/models/database_cluster.yml

@@ -142,7 +142,11 @@ properties:
     type: string
     format: uuid
     example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30
-    description: The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project.<br><br>Requires `project:assign_resource` scope.
+    description: >-
+      The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster,
+      it will be assigned to your default project.
+      <br><br>Requires `project:update` scope. The `project:assign_resource` scope applies to the Projects API
+      resource-assignment endpoints, such as `POST /v2/projects/{project_id}/resources`, and is not sufficient for this check.
   rules:
     type: array
     items:
@@ -175,12 +179,13 @@ properties:
       Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and
       a second entry for the cluster's standby node(s).
     readOnly: true
-  autoscale:
+  storage_autoscale:
     allOf:
-    - $ref: './database_autoscale_params.yml'
+    - $ref: './database_storage_autoscale_params.yml'
     description: >-
-      Autoscaling configuration for the database cluster. Currently only supports storage autoscaling. If null, autoscaling is
-      not configured for the cluster.
+      Storage autoscaling configuration to apply when the cluster is created. If omitted, storage autoscaling is not
+      configured. Autoscaling can also be configured after the cluster is created by sending a PUT request to
+      `/v2/databases/{database_cluster_uuid}/autoscale`.
   do_settings:
     allOf:
     - $ref: './do_settings.yml'