- 27 May 2022
- 3 Minutes to read
Xelon API 101
- Updated on 27 May 2022
- 3 Minutes to read
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:
- Sign up to Postman (a tool we'll use a bit later)
- Sign up or sign in to Xelon HQ
- 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
Same path algorithm will work for tenant IDs, virtual machine IDs, and other instances.
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:
- Go to Manage My Organization and click the green Add Service button on the right
- Enter the Service Name (to help others identify the creator) and your IP address
- Once done, click Add new service and Copy the unique token
Treat your Service Token like you would a bank account password.
Make a request through Postman
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.
curlrequest, your Bearer-type Service Token should be sent as a
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:
- Within the Postman interface, go to File > New > HTTP Request
GETas your method and insert the following URL:
- Select Authorization tab > Type block > Bearer token and insert your Service Token
- 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
ids. Within your tenant array, you can see your unique tenant
Well done, you've made your first API call and retrieved a tenant's
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.
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.
- Open a terminal (Mac or Windows instructions)
- Copy-paste the code below (make sure your token is there too)
- 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.
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:
- Go to the Manage My Organization page
- Within a Service tokens block, find yours and click Delete
- Click Confirm to permanently delete your token
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.