Falcon API (1.2.1)

Download OpenAPI specification:Download

Introduction

This is the documentation of the Falcon application.

WIP: This documentation is currently still in progress.

Getting started

The Falcon API is a RESTful API. The requests and responses are formatted according to the JSON API specification.

Endpoint

The API endpoint URL is https://api.nordan.tech/.

Don't want to work with your live data? For a sandbox environment, you can simply create a test hub and use it to test your application. Simply sign in to Falcon with your username and password and create a new hub. Alternatively, you can use the registration on our (website).

Rate limiting

Our API limits the submission of requests for your application. The limits are managed as the allowed number of operations per time window; an operation can be a read or an update. For authenticated endpoints, API calls are limited to 1000 requests per 60 seconds time window for a user. For unauthenticated endpoints, the limit is 100 requests per 60 seconds time window.

Each response contains the following headers:

  • X-RateLimit-Limit: Maximum number of operations allowed in the current time window.
  • X-RateLimit-Remaining: Number of operations remaining in the current window.

Once the limit is reached, a 429 Too Many Requests response code will be returned along with a Retry-After header, which holds the amount of seconds until a new call can be made.

Only calls who passed authentication do count towards the call limit.

Other restrictions for specific objects (e.g. the maximum length of strings, the range of integers) are documented in the individual API calls.

Authentication

Basically, all endpoints except for a few /auth calls require a JWT (JSON Web Token) token. You will receive this token in the response of an /auth call.

JWT

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "Bearer <TOKEN>"

The payload data of each token is formed from the following items:

Field Name Description
iss Issuer Issuer who created and signed the token.
jti JWT ID Unique identifier for the token.
nbf Not before Token is not valid before this unix timestamp.
iat Issued at Token is issued at this unix timestamp.
exp Expiration time Expiration unix timestamp for the token.
ttl Time to life Time to life (in minutes) for the token.
sub Subject The user fingerprint for the token.
hsu Hash subject The hash value of the subject for the token.
ses Session ID The ID of the session for the token.
hub Hub ID The ID of the hub for the token.
mfa Multi factor authentification Flag for multi factor authentification for the token.
scp Scopes The scope of the token.

A token is only valid for the hub for which it was issued. Attempting to access an item from a different hub with a token that was not issued for that hub will always result in a 404 Not Found response.

Falcon basically provides two ways to authenticate. We recommend that you create a personal access token instead of using a password for the API.

Authentication with password

Using the default method, you authenticate with the user's password.

Validity

All tokens have a validity of 30 minutes by default. This time can be extended to 30 days if you send the remember: true parameter with the /auth call.

A token created by the password procedure will be automatically renewed with every request and extended for 30 minutes or 30 days. The refreshed token is returned along with an Authorization: Bearer <TOKEN> header in the response.

A used token is blacklisted with a grace period of 60 seconds and cannot be used after that. Make sure to update the token after each request in your client and use the new token for the next request.

You can exit the current hub by calling /auth/hub/invalidate or change the hub with /auth/hub. In both cases, the refreshed token will contain the new hub (or no hub if you just invalidated the hub).

Multi-factor authentication

The password authentication may require multi-factor authentication if the user has enabled it or a new device is detected. To complete the authentication you must provide a valid code with the /auth/code request.

Authentication with personal access token

You can create your own personal access tokens in Falcon and use them instead of a user's password.

A personal access token is like a password and should therefore be kept secret under all circumstances.

Personal access tokens can only be created for a specific hub. You can create as many tokens as you like and determine the validity yourself.

Validity

A JWT token created by authentication with personal access token has a fixed validity that you can determine yourself. These tokens are not renewed after each request and cannot be renewed manually.

The validity is always limited to one hub. A hub change is therefore not possible with this token. The number of personal access tokens is unlimited - you can have as many as you need for multiple hubs.

Multi-factor authentication

Multi-factor authentication is skipped if you authenticate with a personal access token.

API Responses

Successful requests

For successful requests, Falcon returns the HTTP 2XX status codes. For a successful create process Falcon returns the response code 201, otherwise 200.

Failed requests

For client side errors, Falcon returns a HTTP 4XX status code if something passed in the request has an error.

Status Code Message Description Possible cuases
401 Unauthorized Invalid Token * Token expired.
* Hub expired.
403 Forbidden Missing permission to perform the action. * Contact your hub admin for permissions for the element.
* Invalid signature.
404 Not found Resource could not be found. * Route doesn't exists.
* Element doesn't exists.
* Element doesn't exists in the given hub from the token.
* Image not readable.
405 Method Not Allowed Invalid request method. * Check the method for the request.
418 I'm a teapot The server refuses the attempt to brew coffee with a teapot. * Drink tea.
422 Unprocessable Content Invalid request data. * Check the "errors" array for detailed error message.
429 Too Many Requests Too many requests to Falcon in the last minute. * Too many requests.
* Too many authorization attempts.
* Too many password resend attempts.
* Too many sms send attempts.

For errors on the server side Falcon returns a HTTP 5XX status code.

Status Code Message Description
502 Bad gateway A service used by Falcon send an invalid response.
503 Service unavailable Falcon unavailable due to mainteance mode.
504 Gateway timeout A service used by Falcon is unavailable.