cURL (Mac and Windows command line)

cURL is a popular command-line utility used to send requests to URLs.

1. Open the Terminal (Mac) or Command Prompt (Windows).

2. Run the following command, replacing <Client ID> and <Client Secret> with the appropriate values from your Application Client:

   curl -X POST "https://auth.getmindful.com/oauth2/token" \
   	-H "Content-Type: application/x-www-form-urlencoded" \
   	-d "grant_type=client_credentials" \
   	-d "client_id=<Client ID>" \
   	-d "client_secret=<Client Secret>"

3. The response will contain an access token:

   {
   	"access_token": "eyJhbGciOiJIUzI1NiIsInR5c...",
   	"token_type": "Bearer",
   	"expires_in": 3600
   }

4. Copy the access_token and use it for API requests for the next hour.

Postman

Postman can be used online or through a desktop application for all major operating systems. In this section, we will discuss sending requests directly to the authentication endpoint vs. allowing Postman to handle authentication automatically.

Import the OpenAPI specification file to create a Postman collection

Before you can authenticate via Postman, you will need to configure the API endpoints in a Postman collection. Rather than manually configuring each endpoint individually, Postman can easily import the OpenAPI spec file and create a new collection automatically.

Follow the steps below to import the file:

1. Download the latest version of the OpenAPI spec file.

   If you already have this file, it is still recommended to download a new copy, because the contents may have changed.

   Note: The file linked above contains the Mindful API V2. OpenAPI spec files are also available for the Mindful API V1 and the Scheduler API, but authentication works differently for the Scheduler API. More information is available about Scheduler API authentication.

2. In Postman, click the Import button above your list of existing collections, then upload the file.

   

3. Before proceeding, click View Import Settings.

   

4. In the Import Settings window, locate the Always inherit authentication setting and toggle it on.

   

   This is not required, but it will make configuring the authentication much more efficient.

5. Exit the Import Settings window, then click Import.

Option 1 — Send requests to the authentication endpoint

1. Create a new POST request to: https://auth.getmindful.com/oauth2/token

2. Navigate to the Body tab and select x-www-form-urlencoded.

3. Add the following key-value pairs, replacing <Client ID> and <Client Secret> with your Application Client credentials:

   • grant_type: client_credentials

   • client_id: <Client ID>

   • client_secret: <Client Secret>

   

4. Click Send.

5. Copy the access_token from the response and use it for requests to Mindful API endpoints.

Option 2 — Configure Postman for automatic authentication

1. Open the API request you want to authenticate or the folder that contains the request.

   Important:

   If you followed the previous instructions to import an OpenAPI spec file, configure authentication at the topmost parent level so that all children can inherit the authentication details.

   

2. In the Authorization tab, configure the fields shown below:

   

   • Auth Type — Select "OAuth 2.0".

   • Access Token URL — Enter https://auth.getmindful.com/oauth2/token or the relevant authentication endpoint (which can be different for QA and other environments).

   • Client ID — Enter your Client ID.

   • Client Secret — Enter your Client Secret.

3. Click Get New Access Token.

   Postman will send a request to the authentication endpoint and display the new token it receives in a modal window.

4. Click Use Token in the modal window that appears.

   

   You should now see the new token populated in the Token field. You can now send requests for this endpoint (or any contained in the folder, if you configured authentication at the folder level), for the next hour.

   Important: If you applied the token to a folder, make sure the set the Auth Type to "Inherit from parent" in the Authorization tab for all endpoints in the folder.

Application code

Since most clients will invoke Mindful APIs via code, this section shows how that might be done in a simple Python script. This will often be done with custom scripting syntax associated with an ACD platform (such as Genesys Cloud), but the Python example below can show you the general logic.

1. Ensure you have Python installed with the "requests" library. If the "requests" library is not installed, install it with pip install requests in a terminal or command prompt.

2. Create a Python script with the following code, replacing the <Client ID>, <Client Secret>, and <Endpoint URL> text with the appropriate values for your test:

   import requests  # Import the requests library for making HTTP requests
   
   # Define the URL for the OAuth 2.0 token request
   url = "https://auth.getmindful.com/oauth2/token"
   
   # Prepare the request payload with authentication details
   payload = {
       "grant_type": "client_credentials",  # Specifies the OAuth 2.0 grant type
       "client_id": "<Client ID>",  # Replace with your actual Client ID
       "client_secret": "<Client Secret>"  # Replace with your actual Client Secret
   }
   
   # Set the request headers
   headers = {"Content-Type": "application/x-www-form-urlencoded"}
   
   # Make a POST request to obtain the access token
   response = requests.post(url, data=payload, headers=headers)
   
   # Check if the request was successful (HTTP status code 200)
   if response.status_code == 200:
       # Extract the access token from the response JSON
       access_token = response.json().get("access_token")
       print("Access Token:", access_token)  # Print the access token for reference
   else:
       # Print an error message if the token request fails
       print("Error:", response.status_code, response.text)
   
   # Use the obtained access token to authenticate API requests
   headers = {"Authorization": f"Bearer {access_token}"}  # Add the token to the Authorization header
   
   # Define the API endpoint you want to access
   api_url = "<Endpoint URL>"
   
   # Make a GET request to the API using the access token
   response = requests.get(api_url, headers=headers)
   
   # Print the API response (JSON format)
   print(response.json())

3. Execute the script in a terminal or command prompt.

   You should see the auth token and API response printed in the terminal. In the following example, we can see the auth token and the response from the "Retrieve all Call Targets" endpoint.