diff --git a/api-docs/swagger.yml b/api-docs/swagger.yml
index 71a4eac8..9f7332a2 100644
--- a/api-docs/swagger.yml
+++ b/api-docs/swagger.yml
@@ -253,6 +253,87 @@ paths:
           description: Not Found
         '500':
           description: Internal Server Error
+  '/system/secrets':
+    get:
+      summary: 'Get a list of secret names and metadata from the provider'
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      responses:
+        '200':
+          description: List of submitted secrets.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/ListSecretsResponse'
+    post:
+      summary: Create a new secret.
+      description: ''
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      parameters:
+      - in: body
+        name: body
+        description: A new secret to create
+        required: true
+        schema:
+          $ref: '#/definitions/SecretInfo'
+      responses:
+        '201':
+          description: Created
+        '400':
+          description: Bad Request
+        '500':
+          description: Internal Server Error
+    put:
+      summary: Update a secret.
+      description: ''
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      parameters:
+      - in: body
+        name: body
+        description: Secret to update
+        required: true
+        schema:
+          $ref: '#/definitions/SecretInfo'
+      responses:
+        '200':
+          description: Ok
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+    delete:
+      summary: Remove a secret.
+      description: ''
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      parameters:
+      - in: body
+        name: body
+        description: Secret to delete
+        required: true
+        schema:
+          $ref: '#/definitions/DeleteSecretRequest'
+      responses:
+        '204':
+          description: OK
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
   '/system/info':
     get:
       summary: Get info such as provider version number and provider orchestrator
diff --git a/gateway/requests/requests.go b/gateway/requests/requests.go
index 015b6c4c..67205700 100644
--- a/gateway/requests/requests.go
+++ b/gateway/requests/requests.go
@@ -91,9 +91,15 @@ type DeleteFunctionRequest struct {
 	FunctionName string `json:"functionName"`
 }
 
-// CreateSecretRequest create a secret w/ annotations
-type CreateSecretRequest struct {
-	Secret Secret `json:"secret"`
+// SecretInfo payload for PUT,POST secret w/ annotations
+type SecretInfo struct {
+	Secret      Secret            `json:"secret"`
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
+// ListSecretsResponse GET response for secrets (value omitted)
+type ListSecretsResponse struct {
+	Secrets []SecretInfo `json:"secrets"`
 }
 
 // DeleteSecretRequest remote a secret by name
@@ -101,9 +107,8 @@ type DeleteSecretRequest struct {
 	SecretName string `json:"secretName"`
 }
 
-// Secret schema use Value only in write-only http verbs
+// Secret schema use Value only in PUT,POST http verbs
 type Secret struct {
-	Name        string             `json:"name"`
-	Value       string             `json:"value"` // write-only
-	Annotations *map[string]string `json:"annotations"`
+	Name  string `json:"name"`
+	Value string `json:"value,omitempty"` // write-only, base64
 }