View, create, and use tokens with the API (#3049)

* fix: broken links in Use Tokens * feature: add Create and View Tokens with the API * update: View, create, and use tokens with the API. Add command-line, curl examples. (#1541) * Update content/influxdb/v2.0/api-guide/api_intro.md * Update token description Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com>
2021-08-23 11:05:07 -05:00 · 2021-08-23 11:05:07 -05:00 · 209f563cfb
parent 2e08bd47bd
commit 209f563cfb
16 changed files with 209 additions and 29 deletions
--- a/content/influxdb/cloud/security/tokens/create-token.md
+++ b/content/influxdb/cloud/security/tokens/create-token.md
@ -1,7 +1,7 @@
 ---
 title: Create a token
 seotitle: Create an API token in InfluxDB
-description: Create an API token in InfluxDB using the InfluxDB UI or the `influx` CLI.
+description: Create an API token in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 menu:
  influxdb_cloud:
    name: Create a token
--- a/content/influxdb/cloud/security/tokens/use-tokens.md
+++ b/content/influxdb/cloud/security/tokens/use-tokens.md
@ -1,7 +1,7 @@
 ---
 title: Use tokens
 seotitle: Use an API token in InfluxDB
-description: Use an API token in InfluxDB using the InfluxDB UI, `influx` CLI, or InfluxDB API
+description: Use an API token in the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 menu:
  influxdb_cloud:
    name: Use tokens
--- a/content/influxdb/cloud/security/tokens/view-tokens.md
+++ b/content/influxdb/cloud/security/tokens/view-tokens.md
@ -1,7 +1,7 @@
 ---
 title: View tokens
 seotitle: View API tokens in InfluxDB
-description: View API tokens in InfluxDB using the InfluxDB UI or the `influx` CLI.
+description: View API tokens in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 aliases:
  - /influxdb/cloud/users/tokens/view-tokens
 menu:
--- a/content/influxdb/v2.0/api-guide/api_intro.md
+++ b/content/influxdb/v2.0/api-guide/api_intro.md
@ -31,13 +31,12 @@ an [InfluxDB Cloud account](/influxdb/cloud/sign-up).

 ### Authentication

-Before diving into the API, use the InfluxDB UI to
+InfluxDB uses [API tokens](/influxdb/v2.0/security/tokens/) to authorize API requests.
+
+1. Before exploring the API, use the InfluxDB UI to
 [create an initial API token](/influxdb/v2.0/security/tokens/create-token/) for your application.

-InfluxDB uses [API tokens](/influxdb/v2.0/security/tokens/) to authorize API requests.
-Include your API token as an `Authorization` header in each request.
-
-#### Example
+2. Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request.

 {{< code-tabs-wrapper >}}
 {{% code-tabs %}}
@ -63,8 +62,6 @@ Postman is another popular tool for exploring APIs. See how to [send authenticat
 Before writing data you'll need to create a Bucket in InfluxDB.
 [Create a bucket](/influxdb/v2.0/organizations/buckets/create-bucket/#create-a-bucket-using-the-influxdb-api) using an HTTP request to the InfluxDB API `/buckets` endpoint.

-#### Example
-
 ```sh
 {{% get-shared-text "api/v2.0/buckets/oss/create.sh" %}}
 ```
--- a/content/influxdb/v2.0/security/tokens/create-token.md
+++ b/content/influxdb/v2.0/security/tokens/create-token.md
@ -1,7 +1,7 @@
 ---
 title: Create a token
 seotitle: Create an API token in InfluxDB
-description: Create an API token in InfluxDB using the InfluxDB UI or the `influx` CLI.
+description: Create an API token in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 aliases:
  - /influxdb/v2.0/users/tokens/create-token/
 menu:
@ -11,10 +11,13 @@ menu:
 weight: 201
 ---

-Create API tokens using the InfluxDB user interface (UI) or the `influx`
-command line interface (CLI).
+Create API tokens using the InfluxDB user interface (UI), the `influx`
+command line interface (CLI), or the InfluxDB API.

-API tokens are visible only to the user who created them and stop working when the user is deactivated. We recommend creating a generic IT user to create and manage tokens for writing data.
+{{% note %}}
+Tokens are visible only to the user who created them and stop working when the user is deactivated.
+We recommend creating a generic IT user to create and manage tokens for writing data.
+{{% /note %}}

 ## Create a token in the InfluxDB UI

@ -35,6 +38,7 @@ API tokens are visible only to the user who created them and stop working when t
 Use the [`influx auth create` command](/influxdb/v2.0/reference/cli/influx/auth/create) to create a token.
 Include flags with the command to grant specific permissions to the token.
 See the [available flags](/influxdb/v2.0/reference/cli/influx/auth/create#flags).
+Only tokens with the `write: authorizations` permission can create tokens.

 ```sh
 # Syntax
@ -50,6 +54,36 @@ influx auth create -o my-org \
  --read-user
 ```

-Filtering options such as filtering by authorization ID, username, or user ID are available.
-See the [`influx auth list` documentation](/influxdb/v2.0/reference/cli/influx/auth/list)
-for information about other available flags.
+See the [`influx auth create` documentation](/influxdb/v2.0/reference/cli/influx/auth/create) for information about other available flags.
+
+## Create a token using the InfluxDB API
+
+Use the `/authorizations` endpoint of the InfluxDB API to create a token.
+
+{{% api-endpoint method="POST" endpoint="/api/v2/authorizations" %}}
+
+Include the following in your request:
+
+| Requirement          | Include by                                               |
+|:-----------          |:----------                                               |
+| API token with the [`write: authorizations`](/influxdb/v2.0/api/#operation/PostAuthorizations) permission  | Use the `Authorization: Token YOUR_API_TOKEN` header.                   |
+| Organization         | Pass as `orgID` in the request body.
+| Permissions list     | Pass as a `permissions` array in the request body.
+
+```sh
+{{% get-shared-text "api/v2.0/auth/oss/token-create.sh" %}}
+```
+
+### Create a token scoped to a user
+
+To scope a token to a user other than the token creator, pass `userID` in the request
+body.
+
+```sh
+{{% get-shared-text "api/v2.0/auth/oss/tokens-create-with-user.sh" %}}
+```
+
+See the
+[`POST /api/v2/authorizations` documentation](/influxdb/v2.0/api/#operation/PostAuthorizations)
+for more information about options.
+
--- a/content/influxdb/v2.0/security/tokens/use-tokens.md
+++ b/content/influxdb/v2.0/security/tokens/use-tokens.md
@ -1,7 +1,7 @@
 ---
 title: Use tokens
 seotitle: Use an API token in InfluxDB
-description: Use an API token in InfluxDB using the InfluxDB UI, `influx` CLI, or InfluxDB API.
+description: Use an API token in the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 aliases:
  - /influxdb/v2.0/users/tokens/use-tokens
 menu:
--- a/content/influxdb/v2.0/security/tokens/view-tokens.md
+++ b/content/influxdb/v2.0/security/tokens/view-tokens.md
@ -1,7 +1,7 @@
 ---
 title: View tokens
 seotitle: View API tokens in InfluxDB
-description: View API tokens in InfluxDB using the InfluxDB UI or the `influx` CLI.
+description: View API tokens in InfluxDB using the InfluxDB UI, the `influx` CLI, or the InfluxDB API.
 aliases:
  - /influxdb/v2.0/users/tokens/view-tokens
 menu:
@ -11,11 +11,12 @@ menu:
 weight: 202
 ---

-View API tokens using the InfluxDB user interface (UI) or the `influx`
-command line interface (CLI).
+View API tokens and permissions using the InfluxDB user interface (UI),
+the `influx` command line interface (CLI), or the InfluxDB API.

 {{% note %}}
-Tokens are visible only to the user who created them and stop working when the user is deactivated. We recommend creating a generic IT user to create and manage tokens for writing data.
+Tokens are visible only to the user who created them and stop working when the user is deactivated.
+We recommend creating a generic IT user to create and manage tokens for writing data.
 {{% /note %}}

 ## View tokens in the InfluxDB UI
@ -38,3 +39,39 @@ influx auth list
 Filtering options such as filtering by authorization ID, username, or user ID are available.
 See the [`influx auth list` documentation](/influxdb/v2.0/reference/cli/influx/auth/list)
 for information about other available flags.
+
+## View tokens using the InfluxDB API
+
+Use the `/authorizations` endpoint of the InfluxDB API to view tokens and permissions.
+
+{{% api-endpoint method="GET" endpoint="/api/v2/authorizations" %}}
+
+Include the following in your request:
+
+| Requirement          | Include by                                               |
+|:-----------          |:----------                                               |
+| API token with the [`read: authorizations`](/influxdb/v2.0/api/#operation/PostAuthorizations) permission  | Use the `Authorization: Token YOUR_API_TOKEN` header.                   |
+
+```sh
+{{% get-shared-text "api/v2.0/auth/oss/tokens-view.sh" %}}
+```
+
+### View a single token
+
+To view a specific authorization and token, include the authorization ID in the URL path.
+
+{{% api-endpoint method="GET" endpoint="/api/v2/authorizations/{authID}" %}}
+
+### Filter the token list
+
+InfluxDB returns authorizations from the same organization as the token used in the request.
+To filter tokens by user, include `userID` as a query parameter in your request.
+
+```sh
+{{% get-shared-text "api/v2.0/auth/oss/tokens-view-filter.sh" %}}
+```
+
+[***Operator tokens***](/{{% latest "influxdb" %}}/security/tokens/#operator-token) have access to all organizations' authorizations.
+To filter authorizations by organization when using an operator token, include an `org` or `orgID` query parameter in your request.
+
+See the [`/authorizations` endpoint documentation](/influxdb/v2.0/api/#tag/Authorizations) for more information about available parameters.
--- a/content/influxdb/v2.0/write-data/delete-data.md
+++ b/content/influxdb/v2.0/write-data/delete-data.md
@ -120,7 +120,7 @@ deletes all data in the specified bucket with timestamps between the specified `
 ##### Delete points in a specific measurement with a specific tag value
 ```sh
 curl --request POST http://localhost:8086/api/v2/delete/?org=example-org&bucket=example-bucket \
-  --header 'Authorization: Token <YOURAUTHTOKEN>' \
+  --header 'Authorization: Token YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2020-03-01T00:00:00Z",
@ -132,7 +132,7 @@ curl --request POST http://localhost:8086/api/v2/delete/?org=example-org&bucket=
 ##### Delete all points in a specified time range
 ```sh
 curl --request POST http://localhost:8086/api/v2/delete/?org=example-org&bucket=example-bucket \
-  --header 'Authorization: Token <YOURAUTHTOKEN>' \
+  --header 'Authorization: Token YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2020-03-01T00:00:00Z",
--- a/shared/text/api/v2.0/auth/oss/token-auth.js
+++ b/shared/text/api/v2.0/auth/oss/token-auth.js
@ -11,7 +11,7 @@ function queryWithToken() {
    host: 'localhost:8086',
    path: "/api/v2",
    headers: {
-      'Authorization': 'Token YourAuthToken',
+      'Authorization': 'Token YOUR_API_TOKEN',
      'Content-type': 'application/json'
    },
  };
--- a/shared/text/api/v2.0/auth/oss/token-auth.sh
+++ b/shared/text/api/v2.0/auth/oss/token-auth.sh
@ -4,7 +4,7 @@
 #######################################

 curl --get "http://localhost:8086/api/v2" \
-  --header "Authorization: Token YourAuthToken" \
+  --header "Authorization: Token YOUR_API_TOKEN" \
  --header 'Content-type: application/json' \
  --data-urlencode "db=mydb" \
  --data-urlencode "q=SELECT * FROM cpu_usage"
--- a/shared/text/api/v2.0/auth/oss/token-create.sh
+++ b/shared/text/api/v2.0/auth/oss/token-create.sh
@ -0,0 +1,34 @@
+INFLUX_ORG_ID=YOUR_ORG_ID
+INFLUX_API_TOKEN=YOUR_API_TOKEN
+
+curl -v --request POST \
+  http://localhost:8086/api/v2/authorizations \
+  --header "Authorization: Token ${INFLUX_API_TOKEN}" \
+  --header 'Content-type: application/json' \
+  --data '{
+  "status": "active",
+  "description": "iot-center-device",
+  "orgID": "'"${INFLUX_ORG_ID}"'",
+  "permissions": [
+    {
+      "action": "read",
+      "resource": {
+        "type": "authorizations"
+      }
+    },
+    {
+      "action": "read",
+      "resource": {
+        "type": "buckets"
+      }
+    },
+    {
+      "action": "write",
+      "resource": {
+        "type": "buckets",
+        "name": "iot-center" 
+      }
+    }
+  ]
+}'
+
--- a/shared/text/api/v2.0/auth/oss/tokens-create-with-user.sh
+++ b/shared/text/api/v2.0/auth/oss/tokens-create-with-user.sh
@ -0,0 +1,45 @@
+######################################################
+# The example below uses common command-line tools 
+# `curl`, `jq` with the InfluxDB API to do the following:
+# 1. Create a user.
+# 2. Find the new or existing user by name.
+# 3. If the user exists:
+#   a. Build an authorization object with the user ID.
+#   b. Create the new authorization.
+#   c. Return the new token.
+######################################################
+
+INFLUX_TOKEN=YOUR_API_TOKEN
+
+function create_token_with_user() {
+  curl --request POST \
+    "http://localhost:8086/api/v2/users/" \
+    --header "Authorization: Token ${INFLUX_TOKEN}" \
+    --header 'Content-type: application/json' \
+    --data "{\"name\": \"$1\"}"
+  
+  curl --request GET \
+    "http://localhost:8086/api/v2/users?name=$1" \
+    --header "Authorization: Token ${INFLUX_TOKEN}" \
+    --header 'Content-type: application/json' | \
+  
+  jq --arg USER $1 '.users[0] // error("User missing")
+    | {
+        "orgID": "YOUR_ORG_ID",
+        "userID": .id,
+        "description": $USER,
+        "permissions": [
+           {"action": "read", "resource": {"type": "buckets"}}
+         ]
+      }' | \
+  
+  curl --request POST \
+    "http://localhost:8086/api/v2/authorizations" \
+    --header "Authorization: Token ${INFLUX_TOKEN}" \
+    --header 'Content-type: application/json' \
+    --data @- | \
+  
+  jq '.token'
+}
+
+create_token_with_user 'iot_user_1'
--- a/shared/text/api/v2.0/auth/oss/tokens-view-filter.sh
+++ b/shared/text/api/v2.0/auth/oss/tokens-view-filter.sh
@ -0,0 +1,27 @@
+# The example below uses the common `curl` and `jq` command-line tools
+# with the InfluxDB API to do the following:
+# 1. Find a user by username and extract the user ID.
+# 2. Find the user's authorizations by user ID.
+# 3. Filter for `active` authorizations that have `write` permission.
+
+INFLUX_TOKEN=YOUR_API_TOKEN
+
+function list_write_auths() {
+  curl "http://localhost:8086/api/v2/users/?name=$1" \
+    --header "Authorization: Token ${INFLUX_TOKEN}" \
+    --header 'Content-type: application/json' | \
+  
+  jq --arg USER $1 '.users[] | select(.name == $USER) | .id' | \
+  
+  xargs -I '%' \
+  curl "http://localhost:8086/api/v2/authorizations/?userID=%" \
+    --header "Authorization: Token ${INFLUX_TOKEN}" \
+    --header 'Content-type: application/json' | \
+  
+  jq '.authorizations[]
+        | select(.permissions[] | select(.action=="write"))
+        | select(.status=="active")'
+}
+
+list_write_auths 'iot_user_1'
+
--- a/shared/text/api/v2.0/auth/oss/tokens-view.sh
+++ b/shared/text/api/v2.0/auth/oss/tokens-view.sh
@ -0,0 +1,6 @@
+INFLUX_TOKEN=YOUR_API_TOKEN
+
+curl --request GET \
+	"http://localhost:8086/api/v2/authorizations" \
+  --header "Authorization: Token ${INFLUX_TOKEN}" \
+  --header 'Content-type: application/json'
--- a/shared/text/api/v2.0/buckets/oss/create.js
+++ b/shared/text/api/v2.0/buckets/oss/create.js
@ -10,7 +10,7 @@ function createBucket() {
    host: 'localhost:8086',
    path: "/api/v2",
    headers: {
-      'Authorization': 'Token YourAuthToken',
+      'Authorization': 'Token YOUR_API_TOKEN',
      'Content-type': 'application/json'
    },
  };
--- a/shared/text/api/v2.0/buckets/oss/create.sh
+++ b/shared/text/api/v2.0/buckets/oss/create.sh
@ -1,5 +1,5 @@
-INFLUX_TOKEN=YourAuthToken
-INFLUX_ORG_ID=your-org-id
+INFLUX_TOKEN=YOUR_API_TOKEN
+INFLUX_ORG_ID=YOUR_ORG_ID

 curl --request POST \
 	"http://localhost:8086/api/v2/buckets" \