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/Organization ID - tells the API which tenant space (or organization) 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.

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. As these applications cannot display the BarTender Cloud login dialog, you'll need to specify a set of credentials to generate the token. More specifically, you must create a user account to act as a service and configure password-based authentication.

For Web Applications, custom interfaces built to make calls and interact with the API use calls to create a login dialog. Underneath the hood, this generates an access token after the identity provider 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 application types, see BarTender 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, you will need to log into the cloud at least once and open the print dialogue for the Print Gateway to be configured.

This will cause BarTender Cloud to communicate with the locally installed Print Gateway and automatically populate the token field.

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

Getting a Bearer Token Using a Sending Application

If you're using a sending application like Insomnia or Postman, make sure you use the following URL when querying BarTender's enhanced identity provider for a bearer token:

https://auth.am1.bartendercloud.com/connect/token?OrganizationDnsName=(organizationIdentifier)

In place of (organizationidentifier), use your Organization Domain ID. See our article on organizations in BarTender Cloud for more details.