/
Running your first REST API method

Running your first REST API method

Owned by Damian Rozmiarkowski
Last updated: Apr 22, 2025 by Duncan Bell

Introduction

This article is a beginner-friendly guide that is intended to help new users get started with the XTM API. It walks you through the essential setup steps, including authentication, using Postman, and making your first REST API call. Whether you are a developer or a project manager who is exploring automation, this guide will give you the foundation you need, to begin working confidently with the XTM API.

Downloading the API software

To start working with the XTM API, you will need a tool for sending and testing HTTP requests. Several options are available, but we recommend using Postman, a user-friendly API client that is widely used by developers and non-developers alike.

Postman makes it easy to organize your API calls, add authentication, view responses, and debug issues. You can download it, free of charge, from the official Postman website – https://www.postman.com/downloads/.

Other tools such as cURL (for command-line users) or Insomnia are also good alternatives, but Postman is especially useful for getting started quickly and managing collections of XTM API calls.

Familiarizing yourself with Postman

Once you have installed Postman, setting up your workspace for the XTM API is quick and straightforward. Follow the steps below to create a clean and organized environment for your API testing:

Step by Step: Setting Up Your Postman Workspace

  1. Open Postman and click on "Workspaces" in the top-left corner of the screen.

  2. Select "Create Workspace", give your new workspace a name such as XTM API Testing and, optionally, add a description.

  3. Choose "Personal" (for local use) or "Team" (if you want to collaborate), then click Create Workspace.

  4. In your new workspace, click the "+" button to open a new tab and start creating requests.

  5. Click "Save" in the top-right corner of the request tab and save it to a new collection (called, for example, XTM API Methods). This helps keep all your requests organized.

  6. In each request, you will be able to set the following:

  • HTTP method (e.g., GET, POST),

  • URL (copied from the XTM API documentation),

  • Headers (e.g., Authorization for the token),

  • Body (if needed. This is typically the case for POST requests, using JSON format).

  1. To build a reusable API toolkit, you can save any requests you create in the future to the same collection.

How to Check API Permissions in the XTM Cloud UI

Before using the XTM API, it is important to make sure your user account has the right permissions and that the API license is active.

To check this, log into your XTM Cloud UI with the account you plan to use for API access. Go to the Users tab, then select the user account you will use to make API calls. Next, open the Access Rights tab. If your XTM Cloud instance has an active API license, you will see an option labeled Access through. Make sure it is set to either User Interface and API or Only API – this ensures that the account is authorized to use the API.

image-20250407-093712.png

How to find the XTM Cloud user’s User ID

To generate an API token using Basic Authentication, you will need the User ID of the account you want to authenticate with.
To find the User ID in the XTM Cloud UI:

  1. Log into the XTM Cloud instance with an account that has permission to view users.

  2. Navigate to the Users tab from the main menu.

  3. Find the user account that you plan to use for accessing the API.

  4. On the right-hand side of the user pane, click the blue “i” (information) icon.

  5. A panel containing details about the user, including the User ID, is displayed.

  6. Copy the User ID and save it for use in your authentication request.

This ID is essential for generating a valid token and must be used exactly as shown.

Accessing the API documentation for your XTM Cloud instance

To access the API documentation for your specific XTM Cloud instance, you can simply append /rest-api to the end of your instance URL. This ensures that you are viewing the correct version of the documentation, which reflects the features and methods available for your setup.

Since new methods are sometimes introduced in different XTM Cloud releases, it is important to refer to your own instance’s documentation rather than a generic source. This is the best way to ensure that you are working with up-to-date and relevant API information.

For example:

  • The documentation for the XTM Cloud instance is available at: https://xtm.cloud/rest-api.

  • The documentation URL for a dedicated instance might look something like: https://yourinstance.xtm-intl.com/rest-api.

 

Basic Authentication to the XTM API

In this section, you will learn how to authenticate to the XTM API using Basic Authentication, the simplest method available.

The examples provided here are based on the XTM Cloud instance (https://api.xtm-cloud.com). If you are using a different XTM Cloud instance, please refer to the earlier section "Accessing API Documentation for Your Instance", which tells you how to adjust the necessary URL accordingly.

To run any API method, authentication is required. You will first need to obtain an authentication token by following the steps below, using Postman.

Step by Step: Authenticating with Basic Authentication in Postman

  1. Open Postman and create a new workspace.

  2. Add a new API request to the workspace.

8888888888.png

  1. Go to the XTM API documentation, and locate the Basic Authentication method.

4444444444444444.png

  1. Copy the request URL shown in the documentation and paste it into the URL field in Postman.

77777777777777777.png

  1. Change the HTTPS method from GET to POST.

  1. Go to the Body tab in Postman and choose raw, then select JSON from the dropdown menu.

  1. Copy the example Body content from the documentation and paste it into the Body section in Postman.

55555555555555.png

  1. Update the request body fields:

  • Replace the "client" value with your XTM company name.

  • Replace the "password" value with your XTM account password.

  • Replace the "user" value with the User ID you will authenticate with (see the "How to Check User ID" section in this article for guidance).

3333333333333333333333333.png

  1. Once all fields have been filled correctly, click the Send button.

111111111111111.png

If everything has been configured correctly, you will receive a 200 OK response from the API. In the response body, you will find your XTM token, which can be used to authenticate future API requests.

22222222222222222.png

Please bear in mind that the data in this example are completely fictional and the token above will not work.

IMPORTANT!

The Basic Authentication method generates a token regardless of whether the data you provide is valid or not. This is because the method simply encodes the values you enter. However, the token will not work in actual API requests unless the credentials (URL, client, password, and user ID) are correct. Each API method decodes the token and verifies the data inside it, so make sure the values you provide are accurate.

Your first API method

Now that you have obtained your authentication token, it is time to test it by calling a real API method. This step is useful for confirming that your token is working properly and that your credentials are correct.

For this example, we will use the "Obtain system details" method, which is a simple request that returns information about your XTM instance. It is ideal for verifying that your token is valid. You can find this method in the XTM API documentation.

Step by Step: Running Your First API Method in Postman

  1. Create a new request in your Postman workspace.

999999999999999.png

  1. Go to the documentation and copy the request URL for the "Obtain system details" method.

365465465656565.png

  1. Paste the URL into the URL field in Postman.

666666.png

  1. Make sure the HTTP method is set to GET.

232323232323223.png

  1. Navigate to the Headers tab in Postman.

  1. Add a new header:

  • Key: Authorization,

  • Value: XTM-Basic YOURTOKENHERE.

Replace YOURTOKENHERE with the token you obtained in the previous step.

  1. Click Send.

If the token is correct, you should receive a 200 OK response along with details about your XTM Cloud instance.

If you receive a 401 Unauthorized response, this either means that the token was applied incorrectly or that the data used to generate the token was invalid. If this is the case, then:

  • check the token generation steps to ensure the correct values were used.

  • try logging into the XTM Cloud UI using the same credentials, to confirm they are valid.