TL;DR InfluxDB Tech Tips; Creating Tokens with the InfluxDB API

By Anais Dotis-Georgiou / Product, Use Cases, Developer
Oct 22, 2020

Navigate to:

Whether you’re using InfluxDB Cloud or InfluxDB OSS, the InfluxDB API provides a simple way to interact with your InfluxDB instance. The InfluxDB v2 API, the read and write portions are available with InfluxDB v1.8+, offers a unified approach to querying, writing data to, and assessing the health of your InfluxDB instances. In today’s Tech Tips post, we learn how to create and list authentication tokens. Tokens provide secure data flow between an InfluxDB instance and its users. Tokens belong to organizations.

Note: In today’s tutorial we’ll use InfluxDB 2.0-rc which runs on port 8086 by default. If you’re running in Cloud or a previous OSS v2 version, replace the URLs with your Cloud URL or http://localhost:9999/ respectively. While you could use any API development tool – like Postman – or curl to execute the API calls described in this TL;DR, we’re using Python and the Requests library to provide examples that could more easily be incorporated in a Python IoT application.

Using the API for secure IoT application development

Automating the creation and listing of tokens with the API is useful for a variety of tasks. For example, imagine you’re building an IoT application on top of InfluxDB. When a new user registers for an account through your application, you’ll want to create a token that has permissions unique to this new user. Upon registration, a write token scoped to a bucket is auto-generated for each user. Additionally, you might decide to provide each user’s device with a different auth token, so you can revoke it later if needed. This approach assumes that the app developer is:

  1. satisfied with the features of the InfluxDB write API and
  2. planning to write their own read/write API to forward secured, authorized read requests to InfluxDB based on their own app requirements.

It’s important to note that giving users direct access to tokens could be problematic and  for the IoT app developer and potentially cumbersome for the end user.

Creating a token with the InfluxDB v2 API

In order to create a token, you’ll need:

  • The correct endpoint from the InfluxDB v2 API Documentation.
  • An All Access token – most likely you'll use the one you generated when you registered for your InfluxDB account. You can find your tokens in the Data tab in the navigation bar.

influxdb token

  • Your orgID. Click on the Account dropdown in the navbar. This is directly above the Data tab where you can find your tokens. This dropdown will list your username as well as org-name. Click on About to get to your user ID and orgID.

influxdb orgid user id

To create a new All Access Token use the following script, which leverages the information we just gathered above:

import requests
import json
url = 'http://localhost:8086/api/v2/authorizations'
# or if you're using InfluxDB Cloud, including the Free Cloud Tier
# url = 'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/authorizations'
headers = {'Authorization': 'Token $INFLUX_TOKEN'}
payload = {
 "orgID": "ec4a5f5fee6ed685",
 "description": "AllAccessAuth",
 "permissions": [
   {
     "action": "read",
     "resource": {
       "type": "authorizations",
     }
   },
   {
     "action": "write",
     "resource": {
       "type": "authorizations",
     }
   },
   {
     "action": "write",
     "resource": {
       "type": "buckets",
     }
   },
   {
     "action": "read",
     "resource": {
       "type": "buckets",
     }
   }
 ]
}
r = requests.post(url, headers=headers, json=payload)
pretty_json = json.loads(r.text)
authID = pretty_json["id"]
token =  pretty_json["token"]
print(json.dumps(pretty_json, indent=2))
print(authID)
print(token)

This token gives you the ability to read and write “authorizations” or tokens. It also gives you the ability to read and write from any bucket. After running the script you should see the following response:

{
  "id": "06739699648b5000",
  "token": "$INFLUX_TOKEN",
  "status": "active",
  "description": "AllAccessAuth",
  "orgID": "ec4a5f5fee6ed685",
  "org": "my-org",
  "userID": "066bc91b58057000",
  "user": "my-username",
  "permissions": [
    {
      "action": "read",
      "resource": {
        "type": "authorizations"
      }
    },
    {
      "action": "write",
      "resource": {
        "type": "authorizations"
      }
    },
    {
      "action": "write",
      "resource": {
        "type": "buckets"
      }
    },
    {
      "action": "read",
      "resource": {
        "type": "buckets"
      }
    }
  ],
  "links": {
    "self": "/api/v2/authorizations/06739699648b5000",
    "user": "/api/v2/users/066bc91b58057000"
  },
  "createdAt": "2020-10-12T14:50:13.138935-05:00",
  "updatedAt": "2020-10-12T14:50:13.138935-05:00"
}
06739ae02b4b5000
pKKPBa__Ck_-3z0FO1qjpd6P6RYiPJIGcFljQ0ygTobEXvCATjpi2DgkqmSKTjFYSRhuEV4tnpjwmn2gP-y9Jw==

We also print the auth ID (aka the token ID) and the token from the json response. The auth ID will be used in the next section to list a specific token. If you want to create a token for reading and writing data that’s scoped to a particular bucket, change the payload to the following:

payload = {
 "orgID": "ec4a5f5fee6ed685",
 "description": "User1",
 "permissions": [
   {
     "action": "write",
     "resource": {
       "type": "buckets",
       "id": "e279b9d2a176f64f",
     }
   },
   {
     "action": "read",
     "resource": {
       "type": "buckets",
       "id": "e279b9d2a176f64f",
     }
   }
 ]
}

In this payload, we only provide a bucket resource and the specific bucket ID we want to scope our token access to. To learn about how to create buckets through the API please take a look at this documentation or this blog. Finally, notice how we include both the read and write action in the payload above to create a read/write token. If you want to create a write-only token that’s scoped to a bucket for individual user or device registration, minimize the payload to the following:

payload = {
 "orgID": "ec4a5f5fee6ed685",
 "description": "Device1",
 "permissions": [
   {
     "action": "write",
     "resource": {
       "type": "buckets",
       "id": "e279b9d2a176f64f",
     }
   }
 ]
}

Listing tokens with the InfluxDB v2 API

In order to list tokens with the InfluxDB v2 API, you need the same information as above. This script allows you to list all of your tokens:

import requests
import json
 
url = 'http://localhost:8086/api/v2/authorizations'
# or if you're using InfluxDB Cloud, including the Free Cloud Tier
# url = 'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/authorizations'
headers = {'Authorization': 'Token $INFLUX_TOKEN'}
r = requests.get('http://localhost:8086/api/v2/authorizations/', headers=headers)
pretty_json = json.loads(r.text)
print(json.dumps(pretty_json, indent=2))

After running the script, you should see all of your tokens listed. This is a portion of the response that includes the token we just created.

{[{
      "id": "06739688dc4b5000",
      "token": "$INFLUX_TOKEN",
      "status": "active",
      "description": "AllAccessAuth",
      "orgID": "ec4a5f5fee6ed685",
      "org": "my-org",
      "userID": "066bc91b58057000",
      "user": "my-username",
      "permissions": [
        {
          "action": "read",
          "resource": {
            "type": "authorizations"
          }
        },
        {
          "action": "write",
          "resource": {
            "type": "authorizations"
          }
        },
        {
          "action": "write",
          "resource": {
            "type": "buckets"
          }
        },
        {
          "action": "read",
          "resource": {
            "type": "buckets"
          }
        }
      ],
      "links": {
        "self": "/api/v2/authorizations/06739688dc4b5000",
        "user": "/api/v2/users/066bc91b58057000"
      },
      "createdAt": "2020-10-12T14:49:56.209911-05:00",
      "updatedAt": "2020-10-12T14:49:56.209911-05:00"
    },
    {
      "id": "06739699648b5000",
      "token": "$INFLUX_TOKEN",
      "status": "active",
      "description": "AllAccessAuth",
      "orgID": "ec4a5f5fee6ed685",
      "org": "my-org",
      "userID": "066bc91b58057000",
      "user": "my-username",
      "permissions": [
        {
          "action": "read",
          "resource": {
            "type": "authorizations"
          }
        },
        {
          "action": "write",
          "resource": {
            "type": "authorizations"
          }
        },
        {
          "action": "write",
          "resource": {
            "type": "buckets"
          }
        },
        {
          "action": "read",
          "resource": {
            "type": "buckets"
          }
        }
      ],
      "links": {
        "self": "/api/v2/authorizations/06739699648b5000",
        "user": "/api/v2/users/066bc91b58057000"
      },
      "createdAt": "2020-10-12T14:50:13.138935-05:00",
      "updatedAt": "2020-10-12T14:50:13.138935-05:00"
    }
  ]
}

In order to list a specific token, you need to provide the auth ID as part of the path parameter. Append your auth ID to your URL as reflected in the following script:

import requests
import json
 
url = 'http://localhost:8086/api/v2/authorizations/06739688dc4b5000'
# or if you're using InfluxDB Cloud, including the Free Cloud Tier
# url = 'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/authorizations/06739688dc4b5000'
headers = {'Authorization': 'Token $INFLUX_TOKEN'}
r = requests.get('http://localhost:8086/api/v2/authorizations/', headers=headers)
pretty_json = json.loads(r.text)
print(json.dumps(pretty_json, indent=2))

Final thoughts about managing tokens with the InfluxDB v2 API

I hope this InfluxDB Tech Tips post inspires you to take advantage of the InfluxDB v2 API to create tokens, and provides you with the examples you need to generate buckets for your IoT application. If you are creating an IoT application or using the API for another reason, please ask us for help and share your story! Share your thoughts, concerns, or questions in the comments section, on our community site, or in our Slack channel. We’d love to get your feedback and help you with any problems you run into!