Authentication

The Nola REST API uses short-lived, OAuth 2.0 Bearer tokens for authentication.

URLs

The OpenID Discovery Endpoint can be found at: https://auth.nolahq.com/realms/nola/.well-known/openid-configuration

Authentication Flow

For writing backend applications that use the Nola REST API, we recommend using the Client Credentials Flow. This flow is designed for server-to-server authentication.

To use this flow, you will need a Client ID and Client Secret, which you can generate from the Nola dashboard (if enabled for your user).

Quick Start

We suggest that you use the available OAuth 2.0 client libraries for your language of choice. These will automatically handle the process of acquiring and refreshing access tokens for you.

Node.js example

The @badgateway/oauth2-client is a good choice in Node.js for this purpose, as it will give us a wrapper to the fetch() API which will automatically authenticate to Nola's REST API.

Install the package:

npm install --save @badgateway/oauth2-client

To create an API client, we need this small function, which takes your Client ID and Client Secret as input:

import { OAuth2Client, OAuth2Fetch } from "@badgateway/oauth2-client";

/**
 * Returns a wrapper around the fetch() API which automatically authenticates
 * to the Nola API, with the given client ID and client secret.
 * @returns {Promise<OAuth2Fetch>}
 */
async function createApiClient(clientID, clientSecret) {
  const client = new OAuth2Client({
    tokenEndpoint:
      "https://auth.nolahq.com/realms/nola/protocol/openid-connect/token",
    clientId: clientID,
    clientSecret: clientSecret,
  });
  const fetchWrapper = new OAuth2Fetch({
    client: client,

    getNewToken: async () => {
      return await client.clientCredentials({
        scope: ["profile", "email", "openid"],
      });
    },
  });
  return fetchWrapper;
}

Using the client is a matter of passing in your Client ID and Client Secret, and then using the returned fetch() wrapper to make requests to the Nola API:

// Example usage: fetch the list of companies your user has access to.
const client = await createApiClient("your-client-id", "your-client-secret");

const response = await client.fetch("https://app.nolahq.com/api/v1/companies");
const companies = await response.json();

console.log(companies);