API Reference

Authentication

API tokens

API tokens allow you connect to Mode’s API programmatically. An API token is used instead of your email address and account password whenever you programmatically authenticate to Mode with basic authentication.

All users that are a part of a Mode Business organization have access to the API, and you can create as many API tokens as you need. Your access to resources in the API directly matches your level of permissions in the Mode organization you’re calling. Before returning a response, Mode validates every API call against your permissions in that organization.

To call the API, you must first create an API access token as follows.

Creating an API access token

WARNING: Remember to store your API token and password securely. Do not expose the password on public sites, in client-side code, or in public code repositories.

  1. Go to the settings page of your Mode account:
    • On the top left of Mode home page, click on your name and select My Account, then API Tokens
    • OR…
    • Click here
  2. Enter a name for the token and click “Create Token” API Token Creation
  3. You’ll see a pop-up window with your API token and password
  4. Copy the token and password and store them someplace safe

The credentials are comprised of two parts:

API Token

  1. Token: The public component of the credential. Often referred to as the the username or access key during authentication.

  2. Password: The private component of the credential. Often refereed to as the password or access secret during authentication.

API tokens are tied to your Mode user account, not to a specific Mode organization. An API token and password generated for your Mode account will provide access to all resources your user account has access to across all Mode organizations to which you belong.

Click Delete next to any current token that you would like to invalidate.

Using an API access token

Once you’ve created an API access token, here is how you can use them for authenticating your API calls.

  1. From the API token username and password you’ve copied, build a string of the form username:password
  2. Encode the string using BASE64 encoding
  3. Supply the encoded string in the HTTP header for authorization in each API call as follows:

    Authorization: Basic "BASE-64 encoded string"

If you use browser tools such as Postman to test your API calls, you can supply a raw username and password in the UI, which will then be encoded and included in the HTTP header when you select basic auth.

All authorized API calls will return an appropriate error code as it applies to the status of resource being called. Unauthorized calls will result in 401 Unauthorized response.

Example — simple request with basic authentication

In this example, you’ll need to change all instances of api_token to your actual API Token and api_secret to your actual API secret.

curl -u api_token:api_secret \
     --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://modeanalytics.com/api/account'
# gem install http

require 'http'
require 'json'

url      = 'https://modeanalytics.com/account'
username = 'api_token'
password = 'api_secret'

response = HTTP.basic_auth(user: username, pass: password)
               .get(url)
puts JSON.parse(response)
import json
import requests

host     = 'https://modeanalytics.com'
username = 'api_token'
password = 'api_secret'

url      = '%s/api/account' % (host)
response = requests.get(url, auth=HTTPBasicAuth(username, password))
result   = response.json()

print result
const request = require('request-promise');

const host     = 'https://modeanalytics.com';
const username = 'api_token';
const password = 'api_secret';

const getAccount = async () => {
  const res = await request({
    url: `${host}/api/account`,
    auth: { username, password },
    json: true,
  });

  return res;
};

console.log(getAccount());