Authentication

Before users can access the BarTender Cloud REST API and send requests, they must complete the authentication process, which ensures that your account is accessed only by authorized users. Authentication provides the bearer access token that all API requests must include.

The authentication method that is used is determined in part by the type of application that your users use to access BarTender Cloud, as follows:

  • Web-based applications use OAuth Code Flow (external link; opens in a new browser tab). When you use this method, access tokens are handled automatically.

  • Console-based applications use OAuth Password Resource Owner Flow (external link; opens in a new browser tab). When you use this method, you must manually allow access to the users whom you want to authorize.

To use an application to access the BarTender Cloud REST API, you must first register it with BarTender Cloud. Then, BarTender Cloud can recognize and support your application, and authorized users can use it connect to the BarTender Cloud API endpoints to create automation scripts. The number of applications that you can register depends on your subscription plan.

You can edit or delete your registered applications, and you can also rotate (change) an application's ID and secret as needed.

To open the BarTender Cloud API page

  • Click to open the BarTender Cloud menu, then click Administration, and select API Keys to display the BarTender Cloud API page.

Closed Configuring a Web-based App for OAuth Access

ClosedTo register a web application with BarTender Cloud

  1. Click Register Application for OAuth Access.

  2. In the Register Web Application dialog, complete the following fields as appropriate:

    • Name: Specifies the name that you want for the web application. This is the "friendly" display name.

    • Description: Specifies an optional description for the web application.

    • Login URI: Specifies the URI for your web application's sign-in page, which is the page that BarTender Cloud will use to sign in to your application (for example: https://mycustom-domain.com/login).

    • Callback List: Specifies one or more URLs for BarTender Cloud to call back to after a user is authenticated. After a user successfully signs in, these URLs redirect to one or more default web pages within your application.

    • Logout URLs: Specifies one or more URLs for BarTender Cloud to redirect to after the user signs out of the web application.

    • Allowed Origins (CORS): Specifies one or more URLs that can make JavaScript requests to the API. These URLs are typically used with cross-origin resource sharing (CORS).

    • Allowed Web Origins: Specifies the URLs where an authorization request that uses cross-origin authentication can come from. These URLs are typically used with CORS.

  3. Click Register. The dialog closes, and your newly registered web application is listed on the BarTender Cloud API page.

ClosedTo view and copy the application ID or secret

  1. In the application list, click for the application that you want, and then click View ID & Secret.

  2. In the Web Registration ID and Secret dialog, click for the application ID or secret to copy it to the clipboard, and then paste it into a secure location.

  3. Click Close.

ClosedTo rotate the application ID and secret

  1. In the application list, click for the application that you want, and then click View ID & Secret.

  2. In the Web Registration ID and Secret dialog, click Rotate ID & Secret.

ClosedTo edit an existing web application

  1. In the application list, click for the application that you want, and then click Edit.

  2. In the Edit Web Application Registration dialog, make the edits that you want, and then click Save.

ClosedTo delete an existing web application

  1. In the application list, click for the application that you want, and then click Delete.

  2. In the Delete Web Application Registration dialog, click Delete Registration.

ClosedConfiguring a Console App for Password-based OAuth Access

ClosedTo register a console application or service with BarTender Cloud

  1. Click Register Application for Password-Based Access.

  2. In the Register Password-Based Access dialog, complete the following fields:

    • Name: Specifies a name for the application or service. This is the "friendly" display name.

    • Description: Specifies an optional description for the application or service.

  3. Click Register. The dialog closes, and your newly registered application or service is listed on the BarTender Cloud API page.

To allow users to access the BarTender Cloud API by using your console application or service, you must select Allow password-based API access for them in the user information dialog that appears when you click Edit for a user on the Users page. For more information, refer to Managing Users.

ClosedTo view and copy the application ID or secret

  1. In the application list, click for the application or service that you want, and then click View ID & Secret.

  2. In the Web Registration ID and Secret dialog, click for the application ID or secret to copy it to the clipboard, and then paste it into a secure location.

  3. Click Close.

ClosedTo rotate the application ID and secret

  1. In the application list, click for the application or service that you want, and then click View ID & Secret.

  2. In the Web Registration ID and Secret dialog, click Rotate ID & Secret.

ClosedTo edit an existing application or service

  1. In the application list, click for the application or service that you want, and then click Edit.

  2. In the Edit Password-Based Access dialog, make the edits that you want, and then click Save.

ClosedTo delete an existing application or service

  1. In the application list, click for the application or service that you want, and then click Delete.

  2. In the Delete Web Application Registration dialog, click Delete Registration.

ClosedTest Access Token

An access token is a long unique alphanumeric string that provides identifying information about the user who is making the API call and the BarTender Cloud tenant space and data center that the call is going to. You add your access token to the script that you write to send API calls to the server, such as cURL commands, PowerShell scripts, and JavaScript scripts.

BarTender Cloud provides a temporary test access token that you can use for testing your application's connection to BarTender Cloud. These test access tokens expire after six months and must be refreshed manually.

ClosedTo view and copy your test access token

  1. Click View Access Token.

  2. In the Personal Access Token dialog, click Copy Access Token to copy the access token to the clipboard, and then paste it into a secure location.

ClosedTo refresh your test access token

  1. Click View Access Token.

  2. In the Personal Access Token dialog, click Refresh Access Token to generate a new access token and automatically copy it to the clipboard.

  3. Paste the access token into a secure location.

Related topics