Falcon API (1.14.1)

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 the functions you know from Falcon are available 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. Keep in mind that you 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/.

If you want your personal sandbox environment, just create a test hub in the production environment and use it to test your application. You can use the registration on our website or simply sign in to Falcon with your user name and password and create a new hub.

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 JWT in the response of an /auth call.

In order to authenticate a request, you can provide the JWT 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 JWT is only valid for the hub for which it was issued. Attempting to access an item from a different hub with a JWT that was not issued for that hub will always result in a 404 Not Found response.

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

Field Name Description
iss Issuer Issuer who created and signed the JWT.
sub Subject The user fingerprint for the JWT.
imp Impersonated user The impersonated user fingerprint for the JWT.
aud Audience Audience for whom the JWT was created.
nbf Not before JWT is not valid before this unix timestamp.
iat Issued at JWT is issued at this unix timestamp.
exp Expiration time Expiration unix timestamp for the JWT.
ttl Time to live Time to live (in minutes) for the JWT.
jti JWT ID Unique identifier for the JWT.
hsu Hash subject The hash of the subject model for the JWT.
pat Personal access token ID The ID of the personal access token for the JWT.
ses Session ID The ID of the user session for the JWT.
hub Hub ID The ID of the hub for the JWT.
mfa Multi factor authentication Flag for multi factor authentication for the JWT.
scp Scopes The scopes of the JWT.

Authentication methods

Falcon basically provides two ways to authenticate:

Password

  • Automatic blacklisting of a JWT with every request
  • Enabled multi-factor authentication process
  • Validity depends on the remember parameter

Personal access token

  • JWT remains valid after request
  • Disabled multi-factor authentication process
  • Validity is defined by the personal access token

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 JWT is blacklisted with a grace period of 60 seconds and cannot be used after that. Make sure to update the JWT after each request in your client and use the new JWT for the next request.

All JWTs 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 JWT created by the password procedure will be automatically renewed with every request and extended for 30 minutes or 30 days. The refreshed JWT 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 JWT 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 JWT created by authentication with personal access token has a fixed validity that you can determine yourself. These JWTs 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 JWT is invalid.
2 Token expired The session has expired.
3 Token blacklisted The session is invalid or has expired.
4 Token invalid The JWT is invalid.
5 Token scopes invalid The JWT is invalid.
6 Token hub not provided The JWT is invalid.
7 Token hub invalid The current hub has been deactivated.
8 Token user invalid The JWT is invalid.
9 Token user session invalid The session is invalid or has expired.
10 Token user token invalid The personal access token is invalid or has expired.
11 User credentials invalid The credentials do not match our records.
12 User credentials password outdated The user password has exceeded the maximum age for passwords.
13 User credentials password compromised The user password has appeared in a data leak and has been reset for security reasons.
14 User login confirmation code invalid The confirmation code is invalid or has expired.
15 User login confirmation status invalid The security settings of the hub require the activation of multi-factor authentication.
16 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.
17 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.
18 User disabled The user has been deactivated. Please contact our support.
19 User hub unauthorized The user does not have the required permissions for the hub.
20 User session terminated The session has been terminated.
21 User session limit exceeded The session limit has been exceeded.
22 User network invalid The IP address of the user does not belong to an allowed network.
23 User invitation invalid There is no valid invitation for this user.
24 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": 1669630792358
}

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.

Precognition

Falcon Precognition allows you to predict the result of a future HTTP request. One of the main use cases of Precognition is the ability to provide "live" validation for your application without having to duplicate the validation rules of the Falcon API.

When Falcon receives a precognitive request, it runs all of the route's middleware and resolves the route's controller dependencies, including validating form requests - but it does not run the route's actual controller method.

Live validation

To use Falcon Precognition, you only need to add the Precognition: true header to an API request.

The Precognition: true header tells Falcon that a client is attempting a Precognition request. The optional Precognition-Validate-Only: <FIELD> header tells Falcon that a client only wants to run the validation rules for the <FIELD> input.

If the validation was successful, the response 204 No Content is returned with the header Precognition-Success: true. If, on the other hand, it was not successful, the normal error response 422 - Unprocessable Content is returned. In addition, the response always contains the header Precognition: true to indicate that it belongs to a Precognition request.

Changelog

v1.14.1 - 2024-05-18

v1.14.0 - 2024-05-01

Added

Changed

  • The budgeting period parameter type has changed from integer (id) to string (budgeting period name).
  • The budgeting period filter parameter type for effects has changed from integer (id) to string (budgeting period name).

v1.13.0 - 2024-03-18

Added

v1.12.0 - 2024-02-28

Added

v1.11.3 - 2024-02-09

Added

  • Added elapsed_plan attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.
  • Added elapsed_actual attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.
  • Added start_time_plan_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.
  • Added start_time_actual_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.
  • Added end_time_plan_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.
  • Added end_time_actual_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.

v1.11.2 - 2024-02-01

Added

  • Added new aud claim to JWT payload.
  • Added pdf preview to hub settings.

Changed

  • A JSON Web Token is now required to open an attachment.
  • Removed signature attribute from all attachment responses.

v1.11.1 - 2024-01-13

Added

  • Added new password_type attribute to the user in the auth response.
  • Added password age to security hub settings.
  • Added new authentication failure code for outdated user password.
  • Added paused attribute to all base elements in nested trees for measure attachments index route, for measure budgeting effect index and show, for measure budgeting total index and show, for measure status report index and show responses.
  • Added paused attribute to all base elements in nested trees for measure package attachments index route, for measure package budgeting effect index and show, for measure package budgeting total index and show, for measure package status report index and show responses.
  • Added paused attribute to all base elements in nested trees for project attachments index route, for project budgeting effect index and show, for project budgeting total index and show, for project status report index and show responses.
  • Added paused attribute to all base elements in nested trees for program attachments index route, for program budgeting effect index and show, for program budgeting total index and show, for program status report index and show responses.
  • Added guarded flag parameter for new projects from setup.

Changed

v1.11.0 - 2023-11-30

Added

  • Added new report type overview for all reports and report subscriptions.

Changed

  • The create request for measure report subscription now needs a report_type.

Fixed

v1.10.8 - 2023-11-10

v1.10.7 - 2023-11-04

Changed

  • Replaced id and hash attributes with measure object in the measure workflow phase response for multiple measures.
  • Replaced id and hash attributes with program object in the budgeting period response without filter.

v1.10.6 - 2023-10-23

v1.10.5 - 2023-10-13

v1.10.4 - 2023-09-22

v1.10.3 - 2023-09-15

Added

Changed

  • For unfiltered budgeting periods, the ID of the program as well as the complete budgeting (instead of just the scaling) has been added to the response. The hash value is now the hash of the program, while the (old) hash value of the response has been changed to "checksum".
  • Added meta data (measure id and hash as well as the workflow) to the measure workflow phase index response for multiple measures.

v1.10.2 - 2023-09-06

Added

v1.10.1 - 2023-08-29

Added

v1.10.0 - 2023-08-17

Added

Changed

  • The tags attribute for creating or updating a measure can be a string for a single tag.

Fixed

  • Added integer as input type for calculation for creating or updating budgeting items.

v1.9.2 - 2023-06-29

Added

  • Added forbidden response if activations are disabled.

v1.9.1 - 2023-06-01

Added

  • Added session limit to hub settings.
  • Added office preview to hub settings.
  • Added new settings array to the user in the auth response, e.g. here.
  • Added new settings array to the hub in the auth response, e.g. here.
  • Added the disposition query paramter to attachment, export and report download route.

Changed

  • Moved the locale attribute to the new settings array of the user in the auth response.

Fixed

  • Changed restrictions for red and yellow threshold for creating budgeting items.
  • Changed restrictions for red and yellow threshold for updating budgeting items.

v1.9.0 - 2023-05-18

v1.8.4 - 2023-05-10

Changed

  • Removed measure workflow phase from measure budgeting effect index and show response.
  • Removed measure workflow phase from measure budgeting total index and show response.

v1.8.3 - 2023-05-03

Added

v1.8.2 - 2023-04-19

Added

  • Added the request to transform a program into a project.
  • Added the request to transform a project into a measure package or into a program.
  • Added the request to transform a measure package into a project.
  • Added the user_hub_permission to all user attributes in permission responses, e.g. for the user of a measure
  • Added status attribute to all user that are part of the responses, e.g. for the responsible user of a user measure permission

Changed

  • The transformation responses do not display the newly created element anymore.

v1.8.1 - 2023-04-06

v1.8.0 - 2023-03-23

Added

v1.7.1 - 2023-02-24

Added

v1.7.0 - 2023-02-17

Added

v1.6.3 - 2023-01-27

v1.6.2 - 2023-01-17

Changed

  • Moved the ttl attribute from the session to the auth response

Fixed

  • Fixed query exception during login
  • Deleted projects are listed in the trash again

v1.6.1 - 2022-12-22

Added

  • Added program status reports
  • Added two new budgeting item period types (rolling year)
  • Added tree element filters for all budgeting effect and budgeting total routes
  • Added start and end time filters for the budgeting effect routes
  • Added start_time_actual_overwritten (to all activity and workflow phase responses) and end_time_actual_overwritten (to all activity responses) attribute

Changed

  • The API now supports the ID or hash value of an object for all identifier parameters (e.g. measure, measure_id, measure_hash)
  • Added limit of characters for budgeting item calculation attribute
  • Increased limit of characters for all description, targets, assumptions, miscellaneous, comment, risks and decisions attributes

Fixed

  • Fixed user and group permission responses
  • Fixed timestamp unprocessable content validation for start_time_actual and end_time_actual for activity (create and update) and workflow phase (update) requests