Question

How does authentication work? What are tokens?

Applicable to 

BarTender Cloud REST API

Answer

The Cloud REST API requires authentication and calls cannot reach the API Gateway. There are no options to use basic authentication or simply send commands without any authentication at all. Unauthorized calls will be stopped by the Authentication Gate and not allowed to continue.

Here is the basic information about how Authentication works.

What are Tokens?

Instead of using a username and password, the API utilizes access tokens. A token is a long series of alphanumeric characters and symbols that looks like nonsense but contains important information about who is making these API calls and where they should go. A token generally looks something like this:

Contained within this token are two key pieces of information

• Tenant ID - tells the API which tenant space this call should go to
• User ID - identifies the user identity of who is making the call

Without this information, the token is denied, and the API call is sent back.

This information is generated by an identity provider, OAuth to be specific. This is the same provider that lets us log into the Cloud in the web interface.

Where can You Find the Token?

Tokens can be located in the Cloud interface under your profile settings or the Manage Cloud Account section. If a tenant space has an automation subscription, the API option will appear at the bottom of the left-hand menu.

Which Applications use a Token?

While all applications making API calls will ultimately use a token, only private applications like Insomnia or Postman explicitly define a token.

Web applications - custom interfaces built to make calls and interact with the API - use OAuth calls to create a login dialog. Underneath the hood, this generates an access token after OAuth verifies the user's identity and behaves much like any other call to the API.

For more information on how Authentication is used and differs between applications types, see Cloud REST API application types

A Special Note About Local Printers and Tokens

To use printers on a specific client system, the client must log into the Cloud at least once to establish a connection. This configuration is done automatically if you install the Print Gateway from the print dialog in the Cloud itself.

If you installed the Print Gateway via installer, not from the Cloud print dialog, and do not log into the Cloud to configure the Print Gateway, there is a special token that will allow that Print Gateway to communicate with the Cloud.

This special token is located at the top of the Print Gateway settings.

This token is only needed if the client system has never logged into the Cloud to configure the Print Gateway. If a Client has logged in or has installed the Print Gateway directly from the print dialog, continue to use the access token provided in the Cloud Settings in the web interface.