Xelon API 101
  • 27 May 2022
  • 3 Minutes to read
  • Dark
  • PDF

Xelon API 101

  • Dark
  • PDF

Article Summary

Just like you, we love to craft and automate things. That's why we're maintaining a public REST API – it allows developers to retrieve and operate Xelon HQ data with HTTP requests.

Already a geek?

If you're familiar with building REST API calls, feel free to skip this section.

If you are new to REST API, this page is a good place to start. We'll guide you with a simple Xelon HQ API request: get the tenant ID.

Make your first API call

Three steps to get started:

  1. Sign up to Postman (a tool we'll use a bit later)
  2. Sign up or sign in to Xelon HQ
  3. Once done, go to the following URL: https:/hq.xelon.ch/api/service/tenant

Well, congrats! That was your first Xelon HQ API request. Let's dive into what just happened.

The base URL for all our API requests is https://hq.xelon.ch/api/service/. We want to get data from our home page, so we go down a level to https://hq.xelon.ch/api/service/tenant.

Pro Tip

Same path algorithm will work for tenant IDs, virtual machine IDs, and other instances.

Authorize youself

We also received a structured JSON-response, but it retrieves an UNAUTHORIZED_REQUEST error. Let's unpack why it happens and how to fix it.

Get a Service Token

Similarly to entering your email and password into our website, when you access Xelon HQ data through API, you'll need to authenticate yourself. The easiest method is to get a Service Token, which you can think of as your unique password for accessing our API.

After you've logged in to Xelon HQ:

  1. Go to Manage My Organization and click the green Add Service button on the right
  2. Enter the Service Name (to help others identify the creator) and your IP address
  3. Once done, click Add new service and Copy the unique token

Create service token.gif

Treat your Service Token like you would a bank account password.

Make a request through Postman

Important note

If you're using the Postman Web Interface (through your browser), your IP won't match your won't Postman Web IP. To get the right IP when using Postman Web, make a GET https://ifconfig.io/ip call which will retrieve the IP you'll need.

For a curl request, your Bearer-type Service Token should be sent as a --header parameter. Example: curl --location --request GET 'https://vdc.xelon.ch/api/service/tenants' \ --header 'Authorization: Bearer <TOKEN>'

Now that we've authenticated ourselves, let's make our API request again:

  1. Within the Postman interface, go to File > New > HTTP Request
  2. Select GET as your method and insert the following URL: https://hq.xelon.ch/api/service/tenants
  3. Select Authorization tab > Type block > Bearer token and insert your Service Token
  4. Click the blue Send button


At the bottom of your Postman window, you'll see a JSON response – we will talk about it in the next section.

If you're getting an error while making a request, double-check your Service Token or linked IP address.

Interpret the response

In the response, you'll see an array of tenants – each with unique names and ids. Within your tenant array, you can see your unique tenant id.

tenant response decypher.png

Well done, you've made your first API call and retrieved a tenant's id!

Our API is documented for what resources are available and what sort of return data to expect. For example, here's the documentation for Tenants endpoint, which we just called.

Explore our API reference

Discover what's possible with Xelon HQ API at developers.xelon.ch.

Make a call through terminal

Instead of Postman, you can work through the terminal – with a pre-installed command line program called cURL – bundled with macOS but also available for Windows.
Let's start:

  1. Open a terminal (Mac or Windows instructions)
  2. Copy-paste the code below (make sure your token is there too)
  3. Press Enter
curl --location --request GET 'https://hq.xelon.ch/api/service/tenants' \
--header 'Authorization: Bearer <YOUR TOKEN GOES HERE>'

If everything is correct, you'll see the same response as we had in Postman, yet Postman makes it easier to scan and understand.

curl call.gif

You're all set to start coding! In our API reference documentation, we often use cURL commands as examples. It is user-friendly enough and works on all platforms.

Delete a Service Token

Sometimes you'll need to generate a new token for your IP address, or just remove the current one. Here's how to do it:

  1. Go to the Manage My Organization page
  2. Within a Service tokens block, find yours and click Delete
  3. Click Confirm to permanently delete your token

delete service token.gif


You can’t undo a deletion of Service Token. Make sure it's not used by your team for any API calls before deleting it.

Was this article helpful?