API Reference

Authentication

API tokens

API tokens allow you to 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.

Your Workspace must be on a paid Mode plan to access the API, and you can create as many API tokens as you need. To call the API, you must first create an API access token. Mode supports two types of access tokens – Workspace API tokens and personal API tokens. New Personal API tokens cannot be created but can continue to be used to authenticate with the API for now.

Workspace API tokens are meant to be used for programmatic management, such as archiving inactive Reports or deleting schedules for stale Reports across your Workspace. These tokens mimic Admin access to the Workspace and only Admins will be able to create and manage them.

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.

Workspace Tokens

Only Admins are able to create Workspace tokens. To create one, navigate to your Workspace Settings > Privacy & Security > API. Click the “gear” icon and select “Create new API token.” You will be prompted to add a display name and save the token.

The credentials are comprised of two parts:

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

  2. Secret: The private component of the credential. Often refereed to as the password or access secret during authentication. This is only shown once when creating the token and must be saved.

Workspace API tokens cannot be used with the following endpoints for now: - Cloning Reports - Invites

Check out Mode’s help site for more information on how to generate and manage a Workspace API token.

(Old) Personal Tokens

Note: You can continue to use personal API tokens with the API. However, you will not be able to generate new personal tokens.

When using personal API tokens, access to resources in the API directly matches your level of permissions in the Mode Workspace you’re calling. Before returning a response, Mode validates every API call against your permissions in that Workspace.

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://app.mode.com/api/account'
# gem install http

require 'http'
require 'json'

url      = 'https://app.mode.com/api/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://app.mode.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://app.mode.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());