Merge pull request #318 from rsyracuse/limited-access-keys

[Update] Limited access keys with Object Storage

Author: leslitagordita

openapi.yaml

@@ -10741,31 +10741,28 @@ paths:
       security:
       - personalAccessToken: []
       - oauth:
-        - object_storage:read_only
+        - object_storage:read_write
       requestBody:
         description: >
           The label of the key to create. This is used to identify the created key.
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                label:
-                  type: string
-                  description: The label for this keypair, for display purposes only.
-                  example: my-key
+              $ref: '#/components/schemas/ObjectStorageKey'
       responses:
         '200':
           description: The new keypair.  **This is the only time** the secret key is returned.
           content:
             application/json:
               schema:
                 allOf:
-                  - $ref: '#/components/schemas/ObjectStorageKey'
-                  - type: object
-                    properties:
-                      secret_key:
-                        example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw
+                - $ref: '#/components/schemas/ObjectStorageKey'
+                - type: object
+                  properties:
+                    secret_key:
+                      type: string
+                      description: This keypair’s secret key. **Only returned on key creation**.
+                      example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw
         default:
           $ref: '#/components/responses/ErrorResponse'
       x-code-samples:
@@ -10774,13 +10771,26 @@ paths:
           curl -H "Content-Type: application/json" \
           -H "Authorization: Bearer $TOKEN" \
             -X POST -d '{
-                "label": "my-object-storage-key"
-            }' \
-            https://api.linode.com/v4/object-storage/keys
+            "label": "my-object-storage-key",
+            "bucket_access": [
+              {
+                "cluster": "ap-south-1",
+                "bucket_name": "bucket-example-1",
+                "permissions": "read_write"
+              },
+              {
+                "cluster": "us-east-1",
+                "bucket_name": "bucket-example-2",
+                "permissions": "read_only"
+              }
+            ]
+          }' \
+          https://api.linode.com/v4/object-storage/keys
       - lang: CLI
         source: >
           linode-cli object-storage keys-create \
-            --label "my-object-storage-key"
+            --label "my-object-storage-key" \
+            --bucket_access '[{"cluster": "ap-south-1", "bucket_name": "bucket-example-1", "permissions": "read_write" }]'
   /object-storage/keys/{keyId}:
     x-linode-cli-command: object-storage
     parameters:
@@ -10841,7 +10851,12 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ObjectStorageKey'
+              type: object
+              properties:
+                label:
+                  type: string
+                  description: The label for this keypair, for display purposes only.
+                  example: my-key
       responses:
         '200':
           description: Update Successful
@@ -10856,7 +10871,7 @@ paths:
         source: >
           curl -H "Content-Type: application/json" \
           -H "Authorization: Bearer $TOKEN" \
-            -x PUT -d '{
+            -X PUT -d '{
               "label": "my-object-storage-key"
             }' \
             https://api.linode.com/v4/object-storage/keys/12345
@@ -10892,7 +10907,7 @@ paths:
       - lang: Shell
         source: >
           curl -H "Authorization: Bearer $TOKEN" \
-            -x DELETE \
+            -X DELETE \
             https://api.linode.com/v4/object-storage/keys/12345
       - lang: CLI
         source: >
@@ -17756,11 +17771,40 @@ components:
           description: This keypair's access key. This is not secret.
           example: KVAKUTGBA4WTR2NSJQ81
           readOnly: true
-        secret_key:
-          type: string
-          description: This keypair's secret key. **Only returned on key creation**.
-          example: '[REDACTED]'
+        limited:
+          type: boolean
+          description: Whether or not this key is a limited access key. Will return `false` if this key grants full access to all buckets on the user's account.
+          example: true
           readOnly: true
+        bucket_access:
+          type: array
+          description: >
+            Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions.
+
+
+              Limited Access Keys can:
+
+              * [list all buckets](/api/v4/object-storage-buckets/) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket.
+
+              * [create new buckets](/api/v4/object-storage-buckets/#post), but do not have any access to the buckets it creates, unless explicitly given access to them.
+          items:
+            type: object
+            properties:
+              cluster:
+                type: string
+                description: The Object Storage cluster where a bucket to which the key is granting access is hosted.
+                example: ap-south-1
+              bucket_name:
+                type: string
+                description: The unique label of the bucket to which the key will grant limited access.
+                example: example-bucket
+              permissions:
+                type: string
+                enum:
+                - read_write
+                - read_only
+                description: This Limited Access Key's permissions for the selected bucket.
+                example: read_only
     PaginationEnvelope:
       type: object
       description: >