Workspot customers using the Entra-ID Only authentication option must use an Entra ID access token instead of Control API’s original username/password authentication method.

This article shows you how to do this. It uses the Postman API platform for examples of a session with the Control API.

Note: Using Postman with the Control API shows you how to use OAuth username/password authentication for AD-based (non-Entra-ID Only) deployments.

Enabling Entra ID Authentication for the Control API

1. Sign into Workspot Control and go to the “Setup > API.” If you do not see an “Auth Type” pull-down menu, Entra ID is not available as an API authentication method.

2. By default, the “Auth Type” is set to “Client & Secret.” Change it to “Azure AD Token (Entra ID).”

3. Note that Control’s Client ID and Client Secret are not used with Entra ID Authentication. Nor are the credentials of a Control administrator used.

Configuring Control API Access in Azure

To access our API services using an Entra ID/Azure AD token, you will need to follow the steps in this section.

Prerequisites

• Workspot API: Contact Support to enable the API if it isn’t enabled already.

• Entra ID Account: Sign into your Entra ID account.

  • Verify that you have the necessary permissions to fetch Entra ID tokens.

  • Verfity that you have configured “Workspot” as an Enterprise Application.

  • Application ID: Locate the Application ID of the "Workspot" Enterprise Application registered in your Entra ID tenant. You will need it later. This can be found by navigating to “Manage > Enterprise Applications.”

  • Tenant ID: The Tenant ID of the Entra ID account. You will need it later. This can be found under “Overview.”

Postman Setup

1. Go to https://www.postman.com/downloads/ and create an account. A free account is adequate. You can use other methods to access the Control API, but this article considers only Postman.

2. Sign into your Postman account.

3. Go to “My Workspace.”

4. Click on “Collections” from the left pane and click on “+” to Create a new collection > Select “Blank Collection.”

5. Give your collection a name. This example uses “Workspot.

6. Click on “…” and select “Add request” and give a name to the request.

Generate an Azure Access Token

We will use Postman to request an access token from Entra ID using OAuth 2.0.

1. In your Postman Workspot collection, Go to “Authorization.”

2. Select “Auth Type” as “Oauth 2.0.”

3. Select “Add authorization data” to “request Headers.”

4. In right section of the “Authorization” tab, fill the fields to get the access token:

• Token name: any name, we used “GetToken.”

• Grant type: Implicit.

• Callback URL: http://localhost

• Authorize using browser: Unchecked.

• Auth URL: https://login.microsoftonline.com/TenantID/oauth2/v2.0/authorize, where TenantID is the Tenant ID you noted above.

• Client ID: The Application ID you noted above.

• Scope: https://graph.microsoft.com/.default offline_access

• Client Authentication: Send client credentials in body.

5. Once the settings are updated, click on “Get New Access Token.”

6. Click on “Proceed” when you see the “Authentication cmoplete” popup.

7. Copy the newly generated Access Token. We will use it soon.

Generate A Control Access Token

We will use the access token we just generated to generate another token: the Control API access token that we’ll use for making API requests.

To generate the Control access token:

1. In the same Postman request we just used or in a new one, update the API call to be:

POST: https://api.workspot.com/oauth/token

2. Go to “Body.”

3. Select “Form-data.”

4. Set “grant_type” to urn:ietf:params:oauth:grant-type:jwt-bearer

5. Set “assertion” to the value of “GetToken” from the previous procedure.

   

6. Once the settings are updated, Click “Send” to send the API request to the Workspot Control API. You should get the Workspot Control Access token in the body of the response.

Calling the Workspot Control API With the Access Token

Now we’re ready to use the Workspot Control API in earnest.

1. Add a new request in the Postman collection to execute API operations.

   • See https://api.us.workspot.com/swagger-ui.html#/api-controller for a list of command and their URLs.

2. In the new Postman request, update the URL with the desired API function and set the method GET, POST, or DELETE as appropriate.

3. In the “Authorization” tab, select “Bearer Token” as the “Auth Type.”

4. Copy the Workspot Access Token from the previous procedure into the “Token” field.

5. You can use this same access token any number of subsequent API requests until the token expires.

   • Always use the “Bearer Token” authentication type.

   • The token expires after one hour (3600 seconds).

Example

As shown in the screenshot below, we are making an API call to retrieve a list of pools within the control. Since no pools currently exist in the Control deployment we are using, the API response is "null."