Falconic Public API Documentation

General

This is the documentation for the public Falconic API. This API is for managing customers and getting protocol information.

Swagger API Specification

For a detailled API description the Swagger specification can be found at /swagger.

Authentication

For authentication, an OAuth 2.0 server is used. The API supports the Client Credentials grant type.

The OAuth 2.0 server is hosted at https://auth.falconic.at.

How to get ClientID and ClientSecret for the API

Each user has the abbility to generate ClientID and ClientSecret for himself. This is done in the Falconic website in the user settings. For security reasons, the ClientSecret won't be stored and is displayed only once while generating the ClientSecret for the user. If the user forgets his ClientSecret, a new ClientSecret can be generated. The old ClientSecret gets invalid at this point.

How to get an Access Token for the API from the OAuth 2.0 server

After a user has generated his ClientID and ClientSecret via the Falconic website, a token can be requested from the OAuth 2.0 server. This is done with the following request, whereas base64EncodedClientIdAndSecret is the base64-encoded form of clientId:clientSecret. The requested scope is public-api, which indicates, that an Access Token for the public Falconic API is requested: 

POST https://auth.falconic.at/connect/token HTTP/2.0
Authorization: Basic base64EncodedClientIdAndSecret
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
scope=public-api
The response is a JSON object which includes an access_token property. This token must be added in the Authentication header like this: Authentication: Bearer <access_token> when calling the public Falconic API . The token has a defined validity duration. This duration is also sent in the JSON response and is defined in the expires_in property, which indicates the expiration time in seconds.

Localization

Request localization is done by setting the Accept-Language header for requests. The same languages as in the Falconic website are supported, e.g. de, en, it, fr. It is recommended, that every request has set the Accept-Language header to make sure the desired language is used.

Rate Limit

The public Falconic API is restricted through a rate limit. This means, that the number of requests in a specific period of time are limited.

The following response headers are returned on a successful response when the rate limit has not been hit: When the rate limit has been reached, an HTTP status code 429 Too Many Requests is returned. In this case, the following response header is set:

Example

Save the following code in a file with the extension .http and open it with e.g. Visual Studio Code and the REST Client extension installed. Replace the clientId and clientSecret with the values you got from the Falconic website and execute the two requests in order. The first one requests a token, the second requests a list of all containers. 

@clientId = 00000000-0000-0000-0000-000000000000
@clientSecret = 0000000000000000000000000000000000000000000=

# @name login
POST https://auth.falconic.at/connect/token HTTP/2.0
Authorization: Basic {{clientId}}:{{clientSecret}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=public-api

###

@token = {{login.response.body.$.access_token}}

GET https://api.falconic.at/v1/Container HTTP/2.0
Authorization: Bearer {{token}}
Content-Type: application/json; charset=utf-8

Breaking Changes

v2.0

v1.0