Authentication

Overview

The Flume API conforms to the OAuth 2 Resource owner credentials grant specification. This is meant to allow individuals to access their own Flume data by utilizing the API. The following page clarifies how the API uses the Password Grant flow, but it is not meant to be a complete guide. To use the API correctly, you should have a clear understanding of OAuth 2.

Requesting a personal client to access the API can be done through the online Portal. The client credentials can be found in the API Access section of the Settings menu. This client will not be able to authenticate any users besides your own.

Step 1: Tokens

Route: Get Tokens

This route is called with the client ID/name and password to get an access token and a refresh token. The client provided by the online Portal will only authenticate the user who requested the client.

On success, the API returns a response envelope containing an access token and a refresh token.

Important: Please make sure that your client ID/name, client secret, access token, and especially the refresh token are stored securely. If someone acquires either token along with the client credentials, they have full access to your account.

The access token is a JSON Web Token (JWT) which contains a few useful bits of information about your account.
A JWT consists of three parts separated by periods (.). The first part is the header, the second part is the payload, and the third part is the signature. More information here.

The payload contains a few useful fields:

user_id: Contains your User ID.
type: Contains the type of user you are.
iat: Contains the date the token was issued in epoch time.
exp: Contains the date the token expires in epoch time.

In order to extract this information from the JWT, there are libraries for most languages here. Alternatively, just extract the payload (middle portion) and base64 decode it to get a JSON object.

To learn more about handling JWTs, visit https://jwt.io/introduction/.

Step 2: Access API

Use your access token by passing it in a Bearer Authorization header like this:

Authorization: Bearer YOUR_KEY_HERE

Most routes require the JWT access token to be present to return a result.

Using the client provided by the online Portal will only permit the user who requested the client to access the API.

If you access token expires, it must be refreshed with the refresh token.
This can be done through the Refresh Access Token route.

Important: Once you have a new access token, delete your old access token. This is for security purposes, because the old token is not automatically invalidated, and will continue to work until it expires.