Falcon API (1.5.2)

Download OpenAPI specification:Download

Introduction

Welcome to the Falcon API.

This technical documentation shows you how to interact with Falcon using our REST-API.

We appreciate your interest and hope to provide you with a detailed source of information. Please note that the documentation is still under construction and parts are still incomplete or missing. We are working under high pressure to complete a stable version.

Getting started

The Falcon API is a RESTful API. Basically, all functions are available to you through the API.

You must specify a Content-Type header with each POST or PUT request so that Falcon can process the input data accordingly. For responses Falcon always uses the Content-Type application/json. Always use UTF-8 as encoding.

All request payload is validated for each individual request. If your payload is incorrect, the response will contain validation errors with details.

The Content-Language header allows you to specify the language in which Falcon should respond. The header is evaluated according to the following definition. Currently Falcon supports the languages de and en.

Endpoint

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

You don't want to work with your live data? For a sandbox environment, you can simply use the integration environment https://integration.api.nordan.tech/, which is also used here in the docs. If you want your personal sandbox environment, just create a test hub in the production environment 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

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

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.

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

Date values

All date values in Falcon are stored in UTC timezone and will be serialized to a UTC ISO-8601 date string (RFC3339) (2016-08-14T22:34:02.000000Z).

For all date input values, the valid date formats are noted in each parameter description.

Authentication

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

In order to authenticate a request, you can provide the token in several ways:

  • As a Authorization: Bearer <TOKEN> header (Recommended).
  • As a token query string in the URL
  • As a token input in the request payload
  • As the Basic Auth password (Authorization: Basic BASE64(:<TOKEN>))

JWT

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "Bearer <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.

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 live Time to live (in minutes) for the token.
sub Subject The user fingerprint for the token.
hsu Hash subject The hash of the subject model for the token.
pat Token ID The ID of the user token for the token.
ses Session ID The ID of the user 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 scopes of the token.

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

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.

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.

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

The validity of personal access tokens is always limited to one hub. It is therefore not possible to change a hub with this type of 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. The number of personal access tokens is unlimited - you can create as many tokens as you like for multiple hubs and determine the validity yourself.

Validity

A JSON web 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. Of course, you can renew the underlying personal access token at any time (even after expiration) in Falcon.

Multi-factor authentication

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

Excluded routes

Some routes cannot be used with personal access tokens. You can find an overview of these routes here:

Authentication failure codes

In case of an authentication failure Falcon returns an failure code in the response. An overview of the authentication failure codes can be found here:

Code Failure Description
0 Unknown
1 Token not provided The token is invalid.
2 Token expired The session has expired.
3 Token blacklisted The session is invalid or has expired.
4 Token invalid The token is invalid.
5 Token scopes invalid The token is invalid.
6 Token hub not provided The token is invalid.
7 Token hub invalid The current hub has been deactivated.
8 Token user invalid The token is invalid.
9 Token user session invalid The session is invalid or has expired.
10 Token user token invalid The user token is invalid or has expired.
11 User credentials invalid The credentials do not match our records.
12 User credentials password compromised The user password has appeared in a data leak and has been reset for security reasons.
13 User login confirmation code invalid The confirmation code is invalid or has expired.
14 User login confirmation status invalid The security settings of the hub require the activation of multi-factor authentication.
15 User login confirmation channel invalid (SMS or authenticator channel required) The security settings of the hub require the activation of multi-factor authentication through SMS confirmation.
16 User login confirmation channel invalid (authenticator channel required) The security settings of the hub require the activation of multi-factor authentication with any authenticator app.
17 User disabled The user has been deactivated. Please contact our support.
18 User hub unauthorized The user does not have the required permissions for the hub.
19 User session terminated The session has been terminated.
20 User session limit exceeded The session limit has been exceeded.
21 User invitation invalid There is no valid invitation for this user.
22 Verification invalid The verification link is invalid or has expired.

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

Client errors

For client side errors, Falcon returns a HTTP 4XX status code if something passed in the request has an error. The four most common client errors are:

401 - Unauthorized

Unauthorized

Response Schema: application/json
success
boolean

The success status of the request.

Value: false
object <array>

The error object.

timestamp
integer

The time of the response.

application/json
{
  • "success": false,
  • "error": {
    },
  • "timestamp": 1653639225756
}

403 - Forbidden

Forbidden

Response Schema: application/json
success
boolean

The success status of the request.

Value: false
object <array>

The error object.

timestamp
integer

The time of the response.

application/json
{
  • "success": false,
  • "error": {
    },
  • "timestamp": 1653056069191
}

404 - Not Found

Not Found

Response Schema: application/json
success
boolean

The success status of the request.

Value: false
object <array>

The error object.

timestamp
integer

The time of the response.

application/json
{
  • "success": false,
  • "error": {
    },
  • "timestamp": 1655800020817
}

422 - Unprocessable Content

Unprocessable Content

Response Schema: application/json
success
boolean

The success status of the request.

Value: false
object <array>

The error object.

timestamp
integer

The time of the response.

application/json
{
  • "success": false,
  • "error": {
    },
  • "timestamp": 1653639225756
}

Client error overview

An overview of all possible client errors:

Code Message Description Possible causes
401 Unauthorized Authentication failed.
403 Forbidden Missing permission to perform the action.
  • Not required permissions.
  • Signature of the request is invalid or expired.
  • Missing input parameter.
404 Not Found Requested resource could not be found.
  • Unsupported request.
  • Bad hostname provided.
  • Requested resource could not be found.
  • Image is broken and cannot be opened.
405 Method Not Allowed Invalid request method.
418 I'm a teapot The server refuses the attempt to brew coffee with a teapot.
422 Unprocessable Content Invalid request data.
429 Too Many Requests Too many requests to Falcon in the last minute.
  • Too many requests.
  • Too many login attempts.
  • Too many password reset attempts.
  • Too many sms send attempts.

Server errors

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

Code Message Description
500 Internal Server Error Oops! This shouldn't have happened. We will take care of this problem as soon as possible.
502 Bad Gateway Oops! A service used by Falcon sends an invalid response.
503 Service Unavailable Oops! Falcon is currently down for maintenance. Be right back!
504 Gateway Timeout Oops! A service used by Falcon is unavailable.