From 043fe36db7eb3ec1e20d701a17d4a10fe22f240a Mon Sep 17 00:00:00 2001
From: Scott Anderson <scott@influxdata.com>
Date: Mon, 9 Sep 2019 17:54:39 -0600
Subject: [PATCH] added example api calls and queries to the manage secrets doc

---
 .../v2.0/security/secrets/manage-secrets.md   | 87 ++++++++++---------
 1 file changed, 46 insertions(+), 41 deletions(-)

diff --git a/content/v2.0/security/secrets/manage-secrets.md b/content/v2.0/security/secrets/manage-secrets.md
index 053f69e45..17826985f 100644
--- a/content/v2.0/security/secrets/manage-secrets.md
+++ b/content/v2.0/security/secrets/manage-secrets.md
@@ -1,6 +1,6 @@
 ---
 title: Manage secrets
-description: Manage secrets in InfluxDB with the API.
+description: Manage secrets in InfluxDB with the InfluxDB API.
 v2.0/tags: [secrets, security]
 menu:
   v2_0:
@@ -9,56 +9,61 @@ weight: 201
 ---
 
 
-The following API calls allow you to manage secrets:
+Manage secrets using the InfluxDB `/org/{orgID}/secrets` API endpoint.
+All secrets belong to an organization and are stored in your [secret-store](/v2.0/security/secrets/).
+Include your [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id)
+and [authentication token](/v2.0/security/tokens/view-tokens/) with each request.
 
-
-### Add secrets to an organization
+### Add a secret
+Use the `PATCH` request method to add a new secret to your organization.
+Pass the secret key-value pair in the request body.
 
 ```sh
-curl --request PATCH \
-  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
-  --header 'authorization: Token YOURAUTHTOKEN' \
-  --header 'content-type: application/json' \
+curl -XPATCH http://localhost:9999/api/v2/orgs/<org-id>/secrets \
+  -H 'authorization: Token YOURAUTHTOKEN' \
+  -H 'Content-type: application/json' \
   --data '{
-	"foo": "bar",
-	"hello": "world"
+	"<secret-key>": "<secret-value>"
 }'
-
-# should return 204 no content
 ```
-### Retrieve an organization's secrets
+
+### View secret keys
+Use the `GET` request method to view your organization's secrets keys.
 
 ```sh
-curl --request GET \
-  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
-  --header 'authorization: Token YOURAUTHTOKEN'
-
-# should return
-#  {
-#    "links": {
-#      "org": "/api/v2/orgs/031c8cbefe101000",
-#      "secrets": "/api/v2/orgs/031c8cbefe101000/secrets"
-#    },
-#    "secrets": []
-#  }
+curl -XGET http://localhost:9999/api/v2/orgs/<org-id>/secrets \
+  -H 'authorization: Token YOURAUTHTOKEN'
 ```
 
-### Retrieve the added secrets
+### Delete a secret
+Use the `POST` request method and the `orgs/{orgID}/secrets/delete` API endpoint
+to delete one or more secrets.
+Include an array of secret keys to delete in the requests body in the following format.
 
 ```bash
-curl --request GET \
-  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
-  --header 'authorization: Token YOURAUTHTOKEN'
-
-# should return
-#  {
-#    "links": {
-#      "org": "/api/v2/orgs/031c8cbefe101000",
-#      "secrets": "/api/v2/orgs/031c8cbefe101000/secrets"
-#    },
-#    "secrets": [
-#      "foo",
-#      "hello"
-#    ]
-#  }
+curl -XGET http://localhost:9999/api/v2/orgs/<org-id>/secrets/delete \
+  --H 'authorization: Token YOURAUTHTOKEN'
+  --data '{
+  "secrets": [
+    "<secret-key>"
+  ]
+}'
+```
+
+## Use secrets in a query
+Import the `influxdata/influxd/secrets` package and use the `secrets.get()` function
+to populate sensitive data in queries with secrets from your secret store.
+
+```js
+import "influxdata/influxdb/secrets"
+import "sql"
+
+username = secrets.get(key: "POSTGRES_USERNAME")
+password = secrets.get(key: "POSTGRES_PASSWORD")
+
+sql.from(
+  driverName: "postgres",
+  dataSourceName: "postgresql://${username}:${password}@localhost",
+  query:"SELECT * FROM example-table"
+)
 ```