How does authentication work? What are tokens?
BarTender Cloud REST API
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 and Auth0, based on the method selected).
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 generated set of credentials to generate the token through Auth0. More specifically, you will need to 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 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 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.