Overview

BarTender Cloud uses OAuth 2.0 with Open ID Connect (OIDC) for web applications to gain access to the BarTender Cloud Rest API. OAuth is an authentication mechanism which allows services to share data with third party web apps. It serves as an alternative to sharing login credentials and the security risks that this entails. OIDC is an open authentication protocol that works on top of the OAuth 2.0 framework. 

This article provides a detailed look at how OAuth works. As this is an advanced topic, this guide is directed at people with a technical background.

Applicable to

BarTender Cloud REST API

Auth0 API

Information

Web Application Registration Process

Register your web applications within BarTender Cloud by clicking on the Hamburger menu icon in the upper left and navigating to Manage Cloud Account > BarTender Cloud API > Register New Web Application.  

Add the Name and Description in the appropriate fields. Explore the requirements below for all remaining fields: 

1. Login URI: Authorization Endpoint within your web application to which the user is redirected. For more information on Redirection click here.
2. Callback List: A list of URLs within your web application to which BarTender Cloud sends its response after authentication. 
3. Logout URLs: Endpoints within your web application to which the user is redirected upon logging out.
4. Allowed Origins (CORS): Although not recommended, cross-origin authentication provides a way to embed authentication forms directly in an application. When embedded login is required, an application must be set up for cross-origin resource sharing (CORS). For more information on CORS click here.
5. Allowed Web Origins: URLs from which cross-origin authentication can be performed. For more information on cross-origin authentication click here.

Find further information on the registration parameters in the help documentation under Web Application > To register a web application with BarTender Cloud.

OAuth Authentication Process

In short, OAuth is a way for you to allow third-party services to access your BarTender Cloud content in your name without revealing your password to this service. It is the authentication process used for web applications accessing the BarTender Cloud Rest API.  

OAuth Technical Details

BarTender Cloud uses the OAuth provider Auth0 to handle the authentication process and third party web applications must use their API in order to authenticate with BarTender Cloud.

BarTender Cloud uses Auth0's Authorization Code Flow for web application authorization and also offers Resource Owner Password Flow for trusted applications.

OAuth Authorization Code Flow

Below is a step-by-step explanation of the application flow when you try to authenticate with BarTender Cloud through a third-party web application(the Client) to access your tenant space:

1. Select Login within the application.

2. Auth0's SDK redirects you to the authorization server. The URLs for this are:

   • BarTender Cloud Americas and APJ environments: https://bartendercloud-production.us.auth0.com/authorize

   • BarTender Cloud EMEA environment: https://bartendercloud-production.eu.auth0.com/authorize

3. The authorization server redirects to the login and authorization prompt.

4. Authenticate using one of the configured login options. You may see a consent prompt listing the permissions that will be given to the application.

5. The authorization server redirects back to application with single-use authorization code.

6. The authorization server verifies the authorization code, Application/client ID, and Application/Client secret.

   • BarTender Cloud Americas and APJ environments: https://bartendercloud-production.us.auth0.com/oauth/token
   • BarTender Cloud EMEA environment: https://bartendercloud-production.eu.auth0.com/oauth/token
   • Application/Client ID used to identify your application -  Generated when the application was registered in BarTender Cloud
   • Application/Client secret used to prove ownership of the ClientID - Generated when the application was registered in BarTender Cloud  

7. The authorization server responds with an ID token and access token (and optionally, a refresh token).

8. The application can use the access token to call the API specified under the Audience paramter to access BarTender Cloud data and functions within its Scope.

   • Audience indicates the specific API Endpoint you want to address.

9. The API responds with requested data.

Auth0 API

You can check out the Web App Quickstart Guide for more information on how to integrate the Auth0 API in your application. 

Additional Resources

Help Documentation:

• Authentication
• C# Automation Example

Support Articles:

• BarTender Cloud REST API Authentications and Tokens
• BarTender Cloud REST API Application Types

Additional External Resources (all rights reserved):

• Understanding OAuth
• Authentication API
• Authorize Application
• Get Token