flowthings.io HTTP API authentication

Token Selection

The flowthings.io API uses tokens for authentication. There are two types of Token available.

Master Token

Each account has a Master Token which, when used, allows full access to any objects that the account owner has access to. The Master Token should be used in cases where the token could not be exposed to unauthorized parties. Sharing a Master Token is as good as sharing your account id and password to flowthings.io.

Do use the Master Token when:

  • The code using the Master Token is running on a secure server
  • The application using the Master Token needs to have access to all Flows, Drops, and/or Tracks that the account owner has created
  • Prototyping in a secure environment

Don’t use the Master Token when:

  • The code using the token is on a physical device that does not require access to all objects the account owner has access to
  • The token will be shared with ANYONE but the account owner

Token

Tokens can be created by anyone to allow specific privilege levels to specific sets of Flows, Drops, or Tracks. To learn more about creating tokens and setting their permissions, see the Token Object Overview.

Do use a Token when:

  • The application using the token only needs to have access to specific Flows, Drops, and/or Tracks
  • You need to time-limit access for a specific application

Authenticating


To use either a master or regular token in a request, supply the token string within the X-Auth-Token header. The API will automatically sandbox any requests made with this Token.

Example Token

{
  "id": "k548b20f2d4c63c0634ad3cc8",
  "tokenString": "SSOjDZ4VMHS2JcwT1sIpE8x91QfG",
  "paths": {
    "/alice/homesecurity/thermostat" : {
      "dropRead" : true,
      "dropWrite": true
    },
    "/alice/homesecurity/reports" : {
      "dropRead" : false,
      "dropWrite": true
    }
   }
}

Using a Token with curl to read a Flow

curl -XGET https://api.flowthings.io/v0.1/alice/flow/<flow_id> -H "X-Auth-Token:<token_string>"