Xelon API 101

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.

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.

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

Make a request through Postman

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.

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.

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.

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.

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